ethora-mcp-cli

Ethora MCP サーバー（Model Context Protocol）

ホスト型サーバーをワンクリックで追加できます。 ブラウザーからサインインするだけで、インストールもキーの貼り付けも必要ありません。

Claude.ai、ChatGPT、Claude Desktop、LM Studioなど、コネクター URL を指定できるものでは、 https://mcp.chat.ethora.com/mcp/oauthを追加してサインインしてください。自分で実行する場合は、 stdio クライアントでの利用をご覧ください。

オープンソースのチャットおよびメッセージングプラットフォームであり、AI エージェントフレームワークを内蔵するEthoraの MCP サーバーです。Claude、ChatGPT、Cursor、Claude Code、VS Code、自律型エージェントからツール呼び出しを通じて、Ethora アプリ、チャットルーム、ユーザー、AI エージェントの作成、メッセージの投稿、RAG ソースのインデックス作成、ウェブサイト用チャットウィジェットの埋め込みコード生成ができます。

Ethora SDK エコシステムの一部です。SDK 間の更新情報：リリースノート。パッケージの変更履歴：CHANGELOG.md。

• npm：https://www.npmjs.com/package/@ethora/mcp-server
• MCP Registry：io.github.dappros/ethora-mcp-server（https://registry.modelcontextprotocol.io/）
• Ethora API（Swagger）：https://api.chat.ethora.com/api-docs/#/

使用方法は3通りです

	実行場所	最適な用途
ホステッド（Ethora Cloud）	https://mcp.chat.ethora.com/mcp（本番環境。https://mcp.chat-qa.ethora.com/mcp は QA インスタンスです）	ローカルへのインストールなしで Ethora Cloud と通信する Claude.ai、ChatGPT、Claude Code、Cursor、エージェント
セルフホスト	Ethora monoserver のデプロイに同梱されています。deploy.yml で services.mcp.enabled を有効にすると、mcp.<your domain>/mcp で利用できます	専用環境またはオンプレミスの Ethora インストール。エージェントの通信がインフラストラクチャの外部に出ることはありません
stdio CLI	マシン上で npx -y @ethora/mcp-server を実行し、環境変数で設定します	ローカル開発、CI、およびコマンドを起動するクライアント

ホステッドモードとセルフホストモードでは、どちらも ETHORA_MCP_TRANSPORT=http を指定して同じサーバーを起動します。MCP セッションごとに独立したインメモリ状態が保持されます。あるクライアントのログイン状態、選択中のアプリ、トークンが別のセッションから見えることはありません。

アカウントメモリ。 クライアントによってはツール呼び出しごとに新しい MCP セッションを開始するため（ChatGPT など）、呼び出し間で選択中のアプリが失われます。そのため、サーバーはサインイン済みアカウントごとに小さなスナップショットを保持します。スナップショットはベアラートークン内のユーザー ID をキーとしており、現在のアプリとエージェント、そのアカウントに現在のアプリ用として API が発行した appToken、有効になっているツールグループが含まれます。同じアカウントのトークン（OAuth、個人用 URL、または Bearer ヘッダー）を持つ新しいセッションには、API に対するトークンの検証後、これらの情報が引き継がれます。メモリはプロセス内に保持され、24時間操作がないと有効期限が切れます。また、ユーザートークン自体が保存されることはありません。同じ問題を解消するため、ほかに2つのデフォルト動作があります。ethora-app-create は新しいアプリを選択し、アプリを1つだけ所有するアカウントでは、最初のアプリスコープの呼び出し時にそのアプリが自動的に選択されます。

60秒で始める

Claude.ai または ChatGPT（カスタムコネクター）。 Ethora のウェブアプリで「Account」を開き、「AI Assistants」タブに移動して API キーを作成し、表示された personal connector URL（https://mcp.chat.ethora.com/mcp/k/<key>）をコピーします。これをカスタムコネクターとして貼り付けます。すべての会話がログイン操作なしで認証されます。ベンダーの OAuth ログインを使用する一覧掲載済みコネクターの場合は、URL は https://mcp.chat.ethora.com/mcp/oauth です。

Claude Code。

# with a personal connector URL (no headers needed)
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp/k/<your API key>

# or the open endpoint plus a Bearer header
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp --header "Authorization: Bearer <your API key>"

URL とヘッダーを指定できる Cursor、VS Code、およびその他のクライアント。

{
  "mcpServers": {
    "ethora": {
      "url": "https://mcp.chat.ethora.com/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}

まだアカウントを持っていない自律型エージェント。 認証情報なしで https://mcp.chat.ethora.com/mcp に接続し、メールアドレス、名、姓を指定して ethora-user-register を呼び出します。アカウントが作成され、セッションにログインし、生成されたパスワード、API キー、connectorUrl が一度だけ返されます。キーを保存し、後で Bearer ヘッダーまたは個人用 URL を使って再接続してください。それ以外は何も必要ありません。ブラウザーもメール確認も不要です。

stdio CLI。

ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-server

続いて、エージェントに ethora-status、ethora-user-login（または ethora-user-register）、ethora-app-list を呼び出すよう依頼します。どの段階で手順が分からなくなっても、ethora-help を呼び出してください。現在の状態を読み取り、次に推奨される呼び出しを返します。

エントリーポイントと認証

エントリーポイント	ID の提供元	一般的なクライアント
/mcp（すべてのツールを最初に一覧表示するには ?tools=all を追加）	接続時には不要です。セッション内で ethora-user-login または ethora-user-register を呼び出すか、すべてのリクエストに Authorization: Bearer <token> を指定します（ユーザー API キー、アプリトークン、または B2B トークン。サーバーはトークンの種類に応じて認証モードを選択します）	エージェント、Claude Code、Cursor、「認証なし」として追加されたコネクター
/mcp/k/<api-key>	パス内のキーを Bearer ヘッダーと同様に適用します	URL は指定できてもヘッダーは指定できない Claude.ai と ChatGPT のカスタムコネクター
/mcp/oauth	Ethora 認可サーバーを通じて取得した OAuth 2.1 アクセストークン（動的クライアント登録、PKCE、アクセススコープ read、write、admin と、それらを必要とするディレクトリー向けの ID スコープ openid、email）	コネクターディレクトリー（Claude、ChatGPT）。ベンダーが独自にログインフローを実行します
stdio	環境変数 ETHORA_APP_JWT（ログイン／登録の初期設定用）と任意の ETHORA_B2B_TOKEN、または実行時の ethora-session-configure	ローカル CLI

ホストされたサーバーではユーザー認証モードを使用してください（ethora-status に authMode: user と表示されます）。アプリトークンモードと B2B モードはサーバー統合用です。エージェントとルームのルートではアプリトークンが拒否されます。

API キー

• ethora-api-key-create { name?, ttlDays? } はキーを生成します（デフォルトは 90 日、有効期間の上限は 365 日）。キーは connectorUrl とともに一度だけ表示されます。ethora-user-register はデフォルトでキーを生成し、ethora-user-login { createApiKey: true } はリクエストに応じて生成します。
• ethora-api-key-list には ID、名前、作成日時、有効期限が表示されますが、キーの値は表示されません。ethora-api-key-revoke { id } はキーを直ちに無効化します。そのキーを使った次のリクエストは REFRESH_RECORD_NOT_FOUND で失敗します。
• 同じキーは Ethora ウェブアプリの「Account」内にある「AI Assistants」で管理できます。個人用 URL、Claude Code 用のワンライナー、Cursor の設定がコピーボタンとともに表示されます。
• キーはユーザー本人として機能します。個人用 URL はパスワードと同様に扱ってください。スクリーンショットを共有せず、漏えいした場合は無効化してください。サーバーはリクエスト URL をログに記録せず、monoserver の nginx テンプレートは MCP ホストでメソッドとステータスのみをログに記録します。

OAuth 2.1 (/mcp/oauth)

認可サーバーをホストする Ethora API の公開 URL を ETHORA_MCP_AUTH_ISSUER に設定します（monoserver のデプロイでは設定済みです）。すると、MCP サーバーは次のように動作します。

• RFC 9728 の保護リソースメタデータを /.well-known/oauth-protected-resource と /.well-known/oauth-protected-resource/mcp/oauth で提供し、認可サーバーと3つのスコープを指定します。
• /mcp/oauth への未認証リクエストに 401 と WWW-Authenticate: Bearer resource_metadata="..." で応答します。これにより、クライアントはフローを検出できます。
• セッションごとに1回（5分間キャッシュ）API で各トークンを検証し、ツールごとにトークンの scope を適用します。読み取り専用ツールには read が必要です。削除、取り消し、ローテーション（および認証情報の表示）には admin が必要です。フィールドを上書きする更新など、その他すべての操作には write が必要です（これらは破壊的操作としてマークされています）。search、fetch、ethora-help、ethora-status、ethora-doctor にはスコープは必要ありません。スコープのクレームがないトークン（API キー）には、完全なアクセス権が付与されます。
• トークンによって本人がすでに特定されるため、ID ツール（ethora-user-login、ethora-user-register、ethora-session-configure、ethora-auth-mode-set、ethora-auth-mode-set、ethora-api-key-create、ethora-api-key-list、ethora-api-key-revoke）を非表示にします。

認可サーバー自体は Ethora バックエンドの一部です。エンドポイントは <issuer>/.well-known/oauth-authorization-server、/oauth/register、/oauth/authorize（サインイン、アカウント作成、Google サインインに対応した同意ページ）、/oauth/token、/oauth/revoke、/oauth/userinfo です。ユーザーは「Account, AI Assistants, Connected AI apps」から OAuth の許可を確認し、接続を解除できます。ETHORA_MCP_AUTH_ISSUER が設定されていない場合、OAuth の両ルートは 404 を返し、検出情報からも除外されます。

ID スコープ。 一部のディレクトリ（ChatGPT）では、OAuth 2.1 に加えて、最小限の OpenID Connect 機能が必要です。具体的には、openid と email のスコープ、および sub、email、email_verified を返す userinfo エンドポイントです。これらのスコープはアプリやデータへのアクセスを許可するものではありません。クライアントがサインインしたユーザーを確認できるようにするだけであり、同意ページにもその旨が平易な言葉で記載されています。ID トークンや JWKS はありません。これらを利用するものがないためです。

メールアドレスの確認は任意です。 Ethora は、確認済みのメールアドレスを必須条件として、サインアップやダッシュボードへのアクセスを制限することはありません。クライアントが ID スコープを要求し、アカウントのメールアドレスがまだ確認されていない場合、同意ページに次の手順が追加されます。確認リンクを送信して確認後に続行するか、メールアドレスを共有せずに続行します（ID スコープは許可から除外され、その他の処理は続行されます）。Google サインインでは確認済みとして扱われるため、この手順は省略されます。確認メールは、ウェブアプリの「Account, AI Assistants」からも送信できます。

エージェントにできること

新規ユーザーが通常求める、ツールを順番に使ったエンドツーエンドの流れです。

1. 認証済みセッションと API キーを取得するために、ethora-user-register（または ethora-user-login）を実行します。
2. ethora-app-create { displayName } を実行し、続けて ethora-app-select { appId } を実行して、新しいアプリを現在のアプリにします。
3. ethora-chat-create { title } を実行してグループルームを作成します。結果にはルーム JID ${appId}_${chatId} が含まれます。ルーム用のすべてのツールでは、JID または chatId のみを指定できます。
4. ethora-agent-create { name, prompt, ... } を実行して、そのアプリに AI エージェントのペルソナを作成します。
5. ethora-agent-invite { agentIdOrAddress, chatJid } を実行して、エージェントをルームに追加します。ボットのインスタンスはその場で起動するため、再起動は不要です。
6. ethora-message-send { text, roomJid, waitForReplySec: 45 } を実行してメッセージを投稿し、エージェントの回答を待ちます。回答は replies として返されます。その後、ethora-chat-history でルームの履歴を読み取ります。
7. ethora-agent-activate { agentId, chatJid } を実行して、そのエージェントをアプリのデフォルトの応答エージェントにします。続けて ethora-widget-snippet-get を実行すると、ウェブサイトに AI チャットウィジェットを配置する <script> タグを取得できます。

ethora-help { goal } を実行すると、このほかのレシピ（user-login、broadcast、sources-ingest、files-upload、bot-manage、chat-test、widget、b2b-bootstrap-ai）も含め、現在の状態に合わせて呼び出しの引数が設定されたレシピが返されます。ethora-recipe-run はそれらを実行します。

最初の1分で覚えておきたい規則

• 作成ツールはすべて同じ形式で応答します。 ethora-app-create、ethora-chat-create、ethora-agent-create は、API オブジェクトの生データに加えて、created（kind、id、name、および該当する場合は jid または address）と、引数が設定済みの呼び出し候補を2～4件含む next を返します。ethora-app-create は、ウェブダッシュボード上のアプリを示す dashboardUrl も返します。
• ethora-help { goal } には、主要な各タスクのレシピがあります。 new-app、in-app-chat、multi-agent-room、widget、chat-test に加え、サーバー統合の目標にも対応しています。いずれも順番に実行する呼び出しと、コピーして使える引数が返されます。
• 発言者がわかります。 ethora-message-send の返信と ethora-chat-history の各行には、senderName と senderKind（human、agent、app）が含まれます。そのため、複数のエージェントがいるルームでも、インスタンス ID ではなく「フロイト：……、ユング：……」のように表示されます。
• 検索は意図を理解します。 search は「React アプリにチャットを追加する」「複数のエージェントが互いに会話する」「メッセージ受信時の webhook」といったユーザーの表現を、回答となるドキュメントに対応付けます。また、doc:not-available は MCP 経由では公開されていない機能と、その機能が利用できる場所を明確に示します。ドキュメント全体は、ID のみ（doc:recipes、doc:chat-component-quickstart、doc:sdk-backend-quickstart、doc:auth-map）を指定して取得できます。

サーバー内のドキュメント

• instructions は、initialize の結果に含まれます。接続に使用したエントリーポイントに応じた認証情報をアシスタントに伝えます。オープンエンドポイントではログインと登録について説明します。個人用 URL と Bearer セッションでは、すでに認証済みであることと、パスワードやキーを決して尋ねてはならないことが伝えられます。OAuth セッションでも同様の情報に加えて、INSUFFICIENT_SCOPE への対処方法が伝えられます。
• search { query } と fetch { id }（ChatGPT コネクターの規約）は、メモリ内のコーパスを検索します。コーパスには、認証マップ、クイックスタート、レシピ、ホスト型の利用開始ガイド、API キーガイド、各ツールの入力情報を記載したリファレンス項目が含まれます。認証なしで利用できます。
• リソース： ethora://docs/auth-map、ethora://docs/chat-component/quickstart、ethora://docs/sdk-backend/quickstart、ethora://docs/recipes。プロンプト： ethora-auth-map、ethora-vite-quickstart、ethora-nextjs-quickstart、ethora-backend-sdk-quickstart、ethora-recipes、ethora-agents-quickstart。

ツールのグループ

セッションの開始時に一覧表示されるのは、core グループのみです。24 個のツールで、「サインインし、アプリを作成し、ルームとメッセージを追加し、エージェントを作成して有効化し、ナレッジベースを与え、ウィジェットを取得する」という一連の流れを網羅し、各操作につき 1 つのバリエーションを提供します。他のグループは登録されていますが非表示のため、tools/list は約 120 KB ではなく約 40 KB に抑えられ、アシスタントが選択する候補も短くなります。

さらに利用する方法は 3 つあります。

• ethora-tools-enable { group } を呼び出すと、セッションでグループが有効になります（または { group: "all" }）。サーバーが tools/list_changed を送信し、クライアントが一覧を更新します。引数なしで呼び出すと、件数付きのカタログが返されます。
• 非表示のツールを名前で呼び出すと、そのグループが有効になり、ツールが実行されます。そのため、ドキュメントや以前のセッションで知った名前が拒否されることはありません。
• エンドポイント URL に ?tools=all を指定する（ホスト型の場合）か、ETHORA_MCP_TOOLS=all を指定する（stdio の場合）と、最初からすべてのツールが一覧表示されます。

search と fetch は非表示のツールについても説明します。各ツールのドキュメントにはグループ名が記載されており、doc:tool-groups はカタログです。レガシー版と非同期版には、優先して使うべき代替ツールを示す先頭行が付いています。

グループ	対象範囲	ツール
core（デフォルトで表示）	サインインまたは登録、アプリの作成、ルームとメッセージの追加、AI エージェントの作成と有効化、ナレッジベースの付与、Web サイトウィジェットの取得。常に表示されます。	ethora-status, ethora-help, ethora-feedback-submit, ethora-tools-enable, search, fetch, ethora-user-register, ethora-user-login, ethora-api-key-create, ethora-app-create, ethora-app-list, ethora-app-select, ethora-app-update, ethora-chat-create, ethora-message-send, ethora-chat-history, ethora-agent-create, ethora-agent-list, ethora-agent-update, ethora-agent-invite, ethora-agent-activate, ethora-source-site-crawl-wait, ethora-source-doc-upload, ethora-widget-snippet-get
keys	API キーの一覧表示と取り消し、アプリの認証情報の表示、アプリトークンの発行とローテーション。	ethora-api-key-list, ethora-api-key-revoke, ethora-app-credentials-reveal, ethora-app-token-create, ethora-app-token-list, ethora-app-token-revoke, ethora-app-token-rotate
session	診断、レシピ、サーバー連携用のセッション認証モード（アプリトークン、B2B トークン）の切り替え。	ethora-doctor, ethora-recipe-run, ethora-session-configure, ethora-auth-mode-set, ethora-auth-mode-set, ethora-auth-mode-set
apps-admin	アプリ全体の削除、エクスポート、インポート、デフォルトのルームの確認。	ethora-app-delete, ethora-app-export, ethora-app-import, ethora-app-rooms-list, ethora-app-rooms-list
rooms	ルームの削除、複数ルームへの一斉送信、メッセージの検索、メッセージのコンテキストと未読件数の確認。	ethora-chat-delete, ethora-broadcast-send, ethora-broadcast-job-get, ethora-broadcast-job-wait, ethora-message-search, ethora-message-context, ethora-chat-unread-counts
agents-admin	エージェントの確認、クローン作成（ナレッジを含める場合と含めない場合）、削除、エクスポート、インポート、ルームなしでのエージェントの試用、ナレッジインデックスの確認と再構築、Memory と可視性の編集。	ethora-agent-get, ethora-agent-clone, ethora-agent-delete, ethora-agent-export, ethora-agent-import, ethora-agent-visibility-set, ethora-agent-soul-set, ethora-agent-soul-append, ethora-agent-try, ethora-agent-knowledge-get, ethora-agent-knowledge-rebuild
sources	ナレッジベースのメンテナンス：非同期のクロールおよび再インデックスジョブ、クロールの停止、サイトとドキュメントの一覧表示とタグ付け、URL とドキュメントの削除。	ethora-source-site-crawl, ethora-source-site-crawl-cancel, ethora-source-site-reindex, ethora-source-site-reindex-wait, ethora-source-site-list, ethora-source-site-watch-list, ethora-source-site-watch-update, ethora-source-site-refresh, ethora-source-site-tags-update, ethora-source-site-url-delete, ethora-source-site-url-delete-batch, ethora-source-doc-list, ethora-source-doc-tags-update, ethora-source-doc-delete
widget	Web サイトウィジェットに保存された外観（色、フォント、サイズ、ランチャー、ティーザー、テキスト）の確認と変更。ライブ埋め込みには、新しいスニペットなしで変更が反映されます。	ethora-widget-appearance-get, ethora-widget-appearance-set
users-files	ユーザーの一括作成と、ファイルのアップロード、取得、削除。	ethora-user-batch-create, ethora-user-batch-job-get, ethora-user-batch-job-wait, ethora-file-upload, ethora-file-get, ethora-file-delete
legacy-bot	agents フレームワーク導入前にダッシュボードで作成されたアプリのアプリごとのボットと、v2 以前のドキュメントツール。新しい用途には agents ツールと sources ツールを優先してください。	ethora-bot-get, ethora-bot-update, ethora-bot-enable, ethora-bot-disable, ethora-bot-widget-get, ethora-bot-history, ethora-bot-message-send, ethora-bot-instance-list, ethora-bot-instance-status-set, ethora-bot-instance-diagnose, ethora-bot-instance-leave, ethora-bot-instance-test, ethora-bot-enable-b2b, ethora-source-doc-upload-legacy, ethora-source-doc-delete-legacy
b2b	B2B トークンを使ったサーバー間のプロビジョニングと、連携用のコードおよび設定ジェネレーター。	ethora-b2b-app-create, ethora-b2b-app-provision, ethora-b2b-app-bootstrap-ai, ethora-b2b-runbook-generate, ethora-env-examples-generate, ethora-chat-component-app-generate, ethora.b2b.auth.use, ethora.b2b.app.create, ethora.b2b.bot.enable, ethora.b2b.broadcast.wait, ethora.b2b.app.bootstrap-ai
wallet	ウォレット残高と ERC-20 の送金。ローカル（stdio）専用で、ホスト型サーバーでは提供されません。	ethora-wallet-balance-get, ethora-wallet-erc20-transfer
ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true の場合に限り、アプリの削除ツールと一括削除ツールが登録されます（monoserver のデプロイでは有効になり、stdio ではデフォルトで無効です）。エイリアスツール（ethora.b2b.*、ethora-bot-message-send、ethora-bot-history）はデフォルトで無効です（公開するには ETHORA_MCP_ENABLE_ALIASES=true を設定します）。正規ツールで同じ操作をすべて行えます。

ウェブサイトウィジェット

ethora-widget-snippet-get は、埋め込み可能な AI チャットウィジェットのタグを返します。

<script id="chat-content-assistant" src="https://widget.<your domain>/assistant.js"
  data-app-id="<appId>" data-api-base="https://api.<your domain>" defer></script>

ウィジェットの外観（色、フォント、サイズ、ランチャー、ティーザーバブル、テキスト）はアプリに保存されます。例：ethora-widget-appearance-set { appearance: { "data-primary-color": "#7c3aed" } }（widget グループ）。これは管理パネルの「App settings」>「AI Widget」と同じ設定です。埋め込みウィジェットは起動時にこの設定を読み込むため、後から変更しても、新しいスニペットを使わずに公開済みのサイトに反映されます。タグに記述された data-* 属性は、そのサイトでは保存済みの値より優先されます。

ウィジェットは、アプリで有効になっているボット（defaultBotInstanceId）を使って応答します。API 経由で作成したアプリでは、まず ethora-agent-create、ethora-chat-create、ethora-agent-invite、ethora-agent-activate { agentId, chatJid } を実行してください。これらの前提条件はツールに記載されており、ethora-help { goal: "widget" } で手順を確認できます。有効化はユーザー認証で実行され、アプリのデフォルトのボットインスタンスを設定します（管理画面の AI Widget ドロップダウンと同じ操作です）。ボットが有効になるまでは、ウィジェットのセッションエンドポイントは AI_BOT_NOT_CONFIGURED を返します。代わりに ethora-chat-component-app-generate を実行すると、@ethora/chat-component 用の React App.tsx が生成されます。

設定

環境変数（stdio およびホスト型）

変数	意味
ETHORA_API_URL	API の完全な URL（例：https://api.chat.ethora.com/v1、デフォルト）。ホスト型サーバーでは、すべてのセッションで固定されます
ETHORA_BASE_URL	ETHORA_API_URL の代わりに指定できるホストのみの値。末尾に /v1 が追加されます
ETHORA_APP_JWT	ログインと登録のみに使われるアプリ JWT（ETHORA_APP_TOKEN は旧式のエイリアスです）
ETHORA_APP_DOMAIN_NAME	ベースアプリの domainName。ETHORA_APP_JWT が空の場合、サーバーは起動時に GET /v1/apps/get-config?domainName=... からアプリ JWT を取得します
ETHORA_B2B_TOKEN	x-custom-token を使うテナントアクタールート向けの B2B サーバートークン
ETHORA_MCP_TOOLS	all を指定すると、コアグループの代わりにすべてのツールを最初から一覧表示します（stdio の場合。ホスト型では URL に ?tools=all を指定します）
ETHORA_MCP_ENABLE_DANGEROUS_TOOLS	true を指定すると、アプリ削除、ウォレット送金、一括削除のツールが登録されます（デフォルトでは無効）
ETHORA_MCP_OPENAI_APPS_CHALLENGE	ホスト型のみ。ドメイン検証用に OpenAI apps ポータルが発行するトークンです。/.well-known/openai-apps-challenge でそのまま提供されます（未設定の場合は 404）
ETHORA_MCP_ENABLE_ALIASES	true を指定すると、ドット区切りの名前空間を使うエイリアスツールを公開します（デフォルトでは無効）

ホストモードのみ

変数	意味
ETHORA_MCP_TRANSPORT	stdio（デフォルト）または http。コマンドラインで --http を指定しても同じです
ETHORA_MCP_HTTP_HOST, ETHORA_MCP_HTTP_PORT	バインドアドレス。デフォルトは 127.0.0.1:3030 です。前段に nginx を配置してください
ETHORA_MCP_PUBLIC_URL	ディスカバリーで通知され、connectorUrl に使用される公開ベース URL。例：https://mcp.chat.ethora.com/mcp
ETHORA_MCP_TRUST_PROXY	true の場合、X-Forwarded-For からクライアントの IP を取得します。呼び出し元ごとに IP 制限が適用されるよう、API に転送されます
ETHORA_MCP_SESSION_TTL_MS	アイドル状態のセッションを削除するまでの時間。デフォルトは 4 時間です
ETHORA_MCP_ACCOUNT_MEMORY_TTL_MS	セッションがない状態で、アカウントの記憶されたコンテキスト（現在のアプリ、エージェント、有効なグループ）を保持する時間。デフォルトは 24 時間です
ETHORA_MCP_AUTH_ISSUER	OAuth 認可サーバー（Ethora API ホスト）の公開 URLです。設定すると /mcp/oauth が有効になります
ETHORA_MCP_WIDGET_URL	ホストされた AI チャットウィジェット（<url>/assistant.js）のベース URLです。ethora-widget-snippet-get で使用されます
ETHORA_MCP_PUBLIC_API_URL	ブラウザーからアクセスできる公開 API ベース URLです。data-api-base として出力されます。未設定の場合は ETHORA_MCP_AUTH_ISSUER、次にループバック以外の ETHORA_API_URL が使用されます

起動時に作業ディレクトリ内の .env ファイルが読み込まれます。実際の環境変数が優先されます。認証情報は ethora-session-configure でセッションごとに設定することもできます（メモリ内のみ。ホストモードのサーバーでは apiUrl を変更できません）。

エンドポイント（ホストモード）

パス	用途
POST|GET|DELETE /mcp	Streamable HTTP MCP エンドポイント。認証なし
POST|GET|DELETE /mcp/k/<api-key>	同じエンドポイント。パス内のキーで認証
POST|GET|DELETE /mcp/oauth	同じエンドポイント。Bearer トークンが必要で、スコープが適用されます
GET /healthz	{ ok, sessions, version, appJwtReady, oauth }
GET /.well-known/mcp および GET /	ディスカバリー JSON：エンドポイント、トランスポート、認証オプション、OAuth メタデータ
GET /.well-known/oauth-protected-resource[/mcp/oauth]	RFC 9728 保護リソースメタデータ

レスポンスエンベロープ

すべてのツールは、次の形式で JSON テキストを返します。成功時は { ok: true, ts, meta, data }、失敗時は { ok: false, ts, meta, error } です。error には code（API 独自のコードがある場合）、message、httpStatus、requestId、1 行の hint が含まれます。

stdio クライアントでの使用

すべての stdio クライアントは npx -y @ethora/mcp-server を実行します。認証情報は環境変数で渡す（推奨）か、手早くローカルでテストする場合は ethora-session-configure を呼び出してください（その引数はトランスクリプトに記録されます）。ホストモードでは、この README の上部にあるワンクリックボタン、またはクイックスタートの URL 形式を使用してください。stdio パッケージ用のワンクリックボタン：

Cursor

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

VS Code（および GitHub Copilot エージェントモード）

.vscode/mcp.json（キーが servers であることに注意してください）：

{ "servers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Claude Code

claude mcp add ethora -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" -- npx -y @ethora/mcp-server

すべてのプロジェクトで使用できるようにするには、--scope user を追加してください。claude mcp list で確認できます。

Claude Desktop

「Settings」、「Developer」、「Edit Config」の順に選択します（claude_desktop_config.json）：

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Gemini CLI、Windsurf、Cline

上記と同じ mcpServers ブロックを、~/.gemini/settings.json、~/.codeium/windsurf/mcp_config.json または cline_mcp_settings.json に設定します。

Codex CLI

~/.codex/config.toml（テーブル名はアンダースコア付きの mcp_servers です）：

[mcp_servers.ethora]
command = "npx"
args = ["-y", "@ethora/mcp-server"]

コンテナ

docker build -t ethora-mcp-server .
docker run -i --rm -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" ethora-mcp-server

コンテナでホストモードを実行するには、-e ETHORA_MCP_TRANSPORT=http -e ETHORA_MCP_HTTP_HOST=0.0.0.0 -p 3030:3030 を追加します。

B2B プロビジョニング（サーバー統合）

ETHORA_B2B_TOKEN を設定すると、ethora-auth-mode-set でセッションをテナントアクター認証に切り替えられます。また、ethora-b2b-app-bootstrap-ai は、1 回の呼び出しでアプリを作成し、ソース（crawlUrl、Base64 形式の docs[]）をインデックス化して、ボットを設定します。llmProvider と llmModel は任意で指定できます。ethora-b2b-app-provision はアプリトークンとデフォルトルームを追加します。ethora-user-batch-create と ethora-user-batch-job-wait を使用すると、ユーザーを非同期でプロビジョニングできます。また、ethora-broadcast-send と ethora-broadcast-job-wait を使用すると、多数のルームにメッセージを送信できます。ethora-b2b-runbook-generate は、独自の自動化で使用する呼び出し順序を出力します。

トラブルシューティング

症状	意味と対処方法
TOKEN_MISSING（401）	セッションにユーザートークンがありません。ethora-user-login または ethora-user-register を呼び出すか、Bearer ヘッダーまたは個人用 URL を使って接続してください
REFRESH_RECORD_NOT_FOUND（401）	API キーまたはトークンが取り消されています。新しいキーを作成してください
/mcp/oauth で INSUFFICIENT_SCOPE（403）	OAuth グラントに、ツールが必要とするスコープ（read、write、admin）がありません。再接続して、より広いスコープを承認してください
This tool requires app-token auth または AUTH_USER_REQUIRED	認証モードが正しくありません。ホストサーバーではユーザーモード（ethora-auth-mode-set）を使用してください。アプリトークンモードは /v2/bot とウィジェットのルート専用です
ウィジェットで AI_BOT_NOT_CONFIGURED が表示される	アプリに有効なボットがありません。エージェントの実行、招待、ethora-agent-activate の手順を行ってから、ページを再読み込みしてください
ethora-bot-* で BOT_NOT_INITIALIZED（422）が表示される	アプリにレガシーのアプリ単位のボットがありません。代わりにエージェント用ツールを使用してください
AGENT_NOT_FOUND または APP_NOT_FOUND（404）	ID が正しくないか、アプリが選択されていません。先に ethora-app-select を実行するか、appId を渡してください
/mcp で Not Acceptable（406）が表示される	クライアントは application/json と text/event-stream の両方を受け入れる必要があります
同意ページに Social sign-in failed (auth/...) と表示される	括弧内の Firebase コードが原因を示します（ブラウザーのコンソールには完全なエラーが表示されます）。auth/popup-blocked の場合は、API ホストでポップアップを許可してください。コードなしのメッセージは 2026-09-17 にバックエンドで修正されました。セルフホストの場合は更新してください
クライアントが接続できない（stdio）	ターミナルで npx -y @ethora/mcp-server を実行し、Node のバージョンが 18 以上であることを確認してください
ホストサーバーが応答しない	GET /healthz を実行してください。appJwtReady: false は、ベースアプリの JWT の初期化に失敗したことを示します（ETHORA_APP_DOMAIN_NAME と ETHORA_API_URL を確認してください）

フィードバック

ethora-feedback-submit は、セッション内からレポート（bug、unexpected、feature、docs、other）を Ethora チームに送信します。Web フォームではなく MCP 経由で送信する理由は、コンテキストを含められることです。セッションで直近に発生したツールの失敗（ツール名、エラーコード、API の requestId）がレポートに添付されるため、記憶を頼りに入力し直さなくても、レポートをサーバー側のログエントリと照合できます。失敗と無関係なレポートの場合は、includeRecentErrors: false を設定してください。

セッションが認証済みかどうかにかかわらず利用できます。最も報告を聞きたいのは、サインアップや認証情報に問題が起きたユーザーだからです。認証済みのレポートはそのアカウントに紐付けられ、匿名のレポートには返信用の email を含められます。また、OAuth スコープの適用対象外なので、読み取り専用の許可でも問題を報告できます。

添付コンテキスト内の認証情報らしきキーは、送信前にマスキングされます。これはキー名に基づく処理のため、自由記述の message に貼り付けられた認証情報は検出できません。ツールの説明では、秘密情報やエンドユーザーの個人データを記載しないようモデルに指示しています。

配信の設定は API 側で行います（FEEDBACK_EMAIL_TO、FEEDBACK_SLACK_WEBHOOK_URL、FEEDBACK_RETENTION_DAYS）。MCP サーバーは送信のみを行います。

利用状況の識別

送信する API 呼び出しには X-Ethora-Client: mcp/<version> が付与され、ツール呼び出し中は X-Ethora-Tool: <tool-name> も付与されます。API はこれらをリクエストログに client および source: mcp:<tool> として記録します。これにより、MCP のトラフィックを Web アプリのトラフィックと区別し、ツールごとに集計できます。認証不要の公開エンドポイント（/ping、/apps/get-config）には、これらの情報は付与されません。

セキュリティに関する注意事項

• ツールの結果から認証情報はマスキングされます。 appSecret、tenantSecret、appToken、パスワードなどのキーは、すべてのツールで [redacted] として返されます（結果はモデルのコンテキストやクライアントのログに入るためです）。ethora-app-credentials-reveal { appId, confirm: true } は、意図的にアプリの appToken を表示するもので、OAuth 経由の admin スコープが必要です。App Secret は Web ダッシュボードの API タブでのみ表示されます。ログイン、登録、API キーやアプリトークンの発行ツールは、仕様上、認証情報を一度だけ返します。

• API キーと個人用 URL は、取り消されるまでユーザーとして機能します。クライアントのシークレットストアに保管し、共有設定やスクリーンショットには含めず、漏えいの疑いがある場合は取り消してください。

• サーバーはリクエスト URL やトークンをログに記録しません。MCP ホストへのリクエストパスがリバースプロキシのアクセスログに残らないようにしてください（monoserver の nginx テンプレートでは記録されません）。

• ツールが返す情報はすべてモデルから参照でき、会話の記録にも保存されます。サーバーはアシスタントに対し、キーやパスワードを出力しないこと、および破壊的なツールの実行前にユーザーへ確認することを指示しています。

• このリポジトリでは、プッシュおよび PR の際に、秘密情報と SAST のレポートのみを生成するスキャン（gitleaks、semgrep）を実行します。

開発

バージョン番号

バージョンはカレンダーに基づき、YY.M.patch の形式です。YY.M はリリース月を表します（26.9.5 は 2026 年 9 月の 5 回目のリリース、26.10.0 は 10 月の 1 回目のリリース）。patch はその月のリリース数を表します。月の先頭にゼロは付けないため、semver では 26.10 は 26.9 より後になります。破壊的変更でもメジャーバージョンは上げず、次のパッチバージョンを付けて変更履歴に記録します。それ以前のツール名はエイリアスとして引き続き呼び出せます。npm run sync-version は、形式が異なる場合、または現在の月と異なる場合に処理を拒否します（意図的に上書きするには ETHORA_VERSION_MONTH=YY.M を指定します）。公開ワークフローでもこのコマンドを実行します。このルールに基づき 2026-09-24 に公開された 27.0.0 と 27.1.0 は非推奨です。26.9.5 は同じコードです。

ツールの命名

27.0 以降、一覧に掲載されるすべてのツールは、次のルールに従います。ethora-<resource>-<verb>[-<qualifier>]。

• resource は単数形の名詞で、1 語または 2 語です。app、agent、chat、message、broadcast、source-site、source-doc、user、file、bot、api-key、app-token、widget、wallet、session、auth-mode、recipe、tools。
• verb は最後の語です。create、list、get、update、delete、send、set、run、reveal、upload、crawl、reindex、start、wait、enable、disable、generate。
• qualifier が動詞の後に付くのは、次の場合のみです。-wait（非同期ジョブのブロッキング形式）、-batch、-legacy、-b2b。
• API バージョンのサフィックスはありません。すべての名前から -v2 がなくなりました。search と fetch は ChatGPT コネクターの慣例に従って、名前をそのまま維持しています。

以前の名前はすべて引き続き使用できます。 古い名前はエイリアスです。tools/list には表示されませんが、呼び出すと正規のツールに書き換えられます（3 つまたは 2 つのツールが 1 つに統合された場合は、あらかじめ引数が設定されます。たとえば ethora-auth-use-app は ethora-auth-mode-set { mode: "app" } になります）。そのため、公開済みの設定、レシピ、保存済みの会話は引き続き機能します。結果と使用状況の帰属には、正規のツール名が表示されます。完全な対応表は、このファイル末尾のエイリアステーブルと src/toolNames.ts にあり、テストスイートでレジストリとの整合性を確認しています。

関連リポジトリ

• ethora-chat-component：ウィジェットとスタンドアロンアプリで使用される React チャットコンポーネント
• ethora-monoserver：このサーバーをオプションサービスとして提供するデプロイ自動化ツール（プライベートリポジトリ。エンタープライズのお客様が利用できます）
• ethora-wp-plugin：WordPress との統合
• rag_demos：RAG AI アシスタントの例

品質と保守性のスコア

Glama による独立した評価を受けています。Glama はサーバーをビルドし、ツールをカタログ化して、ツール定義の品質とメンテナンス活動を評価します。

以前のツール名

27.0 より前に使用されていた名前と、それぞれの名前が現在対応するツールです。どの名前も引き続き呼び出すことができます。

Earlier name	Canonical tool
ethora-agents-activate-v2	ethora-agent-activate
ethora-agents-clone-v2	ethora-agent-clone
ethora-agents-create-v2	ethora-agent-create
ethora-agents-delete-v2	ethora-agent-delete
ethora-agents-export-v2	ethora-agent-export
ethora-agents-get-v2	ethora-agent-get
ethora-agents-import-v2	ethora-agent-import
ethora-agent-invite-to-chat	ethora-agent-invite
ethora-agents-list-v2	ethora-agent-list
ethora-agents-update-v2	ethora-agent-update
ethora-agent-set-visibility	ethora-agent-visibility-set
ethora-app-credentials	ethora-app-credentials-reveal
ethora-app-export-v2	ethora-app-export
ethora-app-import-v2	ethora-app-import
ethora-app-get-default-rooms	ethora-app-rooms-list
ethora-app-get-default-rooms-with-app-id	ethora-app-rooms-list
ethora-app-tokens-create-v2	ethora-app-token-create
ethora-app-tokens-list-v2	ethora-app-token-list
ethora-app-tokens-revoke-v2	ethora-app-token-revoke
ethora-app-tokens-rotate-v2	ethora-app-token-rotate
ethora-auth-use-app	ethora-auth-mode-set with {"mode": "app"}
ethora-auth-use-b2b	ethora-auth-mode-set with {"mode": "b2b"}
ethora-auth-use-user	ethora-auth-mode-set with {"mode": "user"}
ethora.b2b.auth.use	ethora-auth-mode-set with {"mode": "b2b"}
ethora.b2b.app.bootstrap-ai	ethora-b2b-app-bootstrap-ai
ethora.b2b.app.create	ethora-b2b-app-create
ethora-generate-b2b-bootstrap-runbook	ethora-b2b-runbook-generate
ethora-bot-disable-v2	ethora-bot-disable
ethora-bot-enable-v2	ethora-bot-enable
ethora-b2b-bot-enable	ethora-bot-enable-b2b
ethora.b2b.bot.enable	ethora-bot-enable-b2b
ethora-bot-get-v2	ethora-bot-get
ethora-bot-history-v2	ethora-bot-history
ethora-bot-instance-diag	ethora-bot-instance-diagnose
ethora-bot-instance-leave-chat	ethora-bot-instance-leave
ethora-bot-instances-list	ethora-bot-instance-list
ethora-bot-instance-status	ethora-bot-instance-status-set
ethora-bot-instance-test-message	ethora-bot-instance-test
ethora-bot-message-v2	ethora-bot-message-send
ethora-bot-update-v2	ethora-bot-update
ethora-bot-widget-v2	ethora-bot-widget-get
ethora-chats-broadcast-job-v2, ethora-broadcast-job-start	ethora-broadcast-job-get
ethora-wait-broadcast-job-v2	ethora-broadcast-job-wait
ethora.b2b.broadcast.wait	ethora-broadcast-job-wait
ethora-chats-broadcast-v2	ethora-broadcast-send
ethora-generate-chat-component-app-tsx	ethora-chat-component-app-generate
ethora-app-create-chat	ethora-chat-create
ethora-app-delete-chat	ethora-chat-delete
ethora-chats-history-v2	ethora-chat-history
ethora-unread-counts-v2	ethora-chat-unread-counts
ethora-generate-env-examples	ethora-env-examples-generate
ethora-files-delete-v2	ethora-file-delete
ethora-files-get-v2	ethora-file-get
ethora-files-upload-v2	ethora-file-upload
ethora-messages-context-v2	ethora-message-context
ethora-messages-search-v2	ethora-message-search
ethora-chats-message-v2	ethora-message-send
ethora-run-recipe	ethora-recipe-run
ethora-configure	ethora-session-configure
ethora-sources-docs-delete-v2	ethora-source-doc-delete
ethora-sources-docs-delete	ethora-source-doc-delete-legacy
ethora-sources-docs-list-v2	ethora-source-doc-list
ethora-sources-docs-tags-update-v2	ethora-source-doc-tags-update
ethora-sources-docs-upload-v2	ethora-source-doc-upload
ethora-sources-docs-upload	ethora-source-doc-upload-legacy
ethora-sources-site-crawl-v2	ethora-source-site-crawl
ethora-sources-site-crawl-v2-wait	ethora-source-site-crawl-wait
ethora-sources-site-list-v2	ethora-source-site-list
ethora-sources-site-reindex-v2	ethora-source-site-reindex
ethora-sources-site-reindex-v2-wait	ethora-source-site-reindex-wait
ethora-sources-site-tags-update-v2	ethora-source-site-tags-update
ethora-sources-site-delete-url-v2	ethora-source-site-url-delete
ethora-sources-site-delete-url-v2-batch	ethora-source-site-url-delete-batch
ethora-users-batch-create-v2	ethora-user-batch-create
ethora-users-batch-job-v2, ethora-user-batch-job-start	ethora-user-batch-job-get
ethora-wait-users-batch-job-v2	ethora-user-batch-job-wait
ethora-wallet-get-balance	ethora-wallet-balance-get
ethora-widget-embed-snippet	ethora-widget-snippet-get

License

See LICENSE.