ethora-mcp-cli

Ethora MCP 服务（模型上下文协议）

一键添加托管服务。 通过浏览器登录即可；无需安装，也无需粘贴密钥。

对于 Claude.ai、ChatGPT、Claude Desktop、LM Studio 以及其他支持连接器 URL 的产品，添加 https://mcp.chat.ethora.com/mcp/oauth 并登录。想自行运行？请参阅 与 stdio 客户端搭配使用。

Ethora 的 MCP 服务。Ethora 是一个开源聊天和消息平台，内置 AI Agent 框架。借助工具调用，它可以让 Claude、ChatGPT、Cursor、Claude Code、VS Code 和自主 Agent 创建 Ethora 应用、聊天室、用户和 AI Agent，发布消息、为 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/#/

三种使用方式

	运行位置	适用场景
托管版（Ethora Cloud）	https://mcp.chat.ethora.com/mcp（生产环境；https://mcp.chat-qa.ethora.com/mcp 是 QA 实例）	Claude.ai、ChatGPT、Claude Code、Cursor，以及无需本地安装即可与 Ethora Cloud 通信的 Agent
可自托管版	随 Ethora monoserver 部署提供；在 deploy.yml 中启用 services.mcp.enabled，服务地址为 mcp.<your domain>/mcp	专用或本地部署的 Ethora 安装；Agent 流量不会离开你的基础设施
stdio CLI	在你的机器上运行 npx -y @ethora/mcp-server，并使用环境变量配置	本地开发、CI，以及可启动命令的客户端

托管模式和可自托管模式使用同一个服务，通过 ETHORA_MCP_TRANSPORT=http 启动。每个 MCP 会话都有私有的内存状态：一个客户端的登录信息、所选应用或令牌不会被其他会话看到。

账户记忆。 某些客户端每次调用工具都会开启新的 MCP 会话（ChatGPT 就是这样），这会导致所选应用在调用之间丢失。因此，服务会按已登录账户保存一份小型快照，并以 Bearer 令牌中的用户 ID 为键：包括当前应用和 Agent、API 为该账户的当前应用提供的 appToken，以及已启用的工具组。使用同一账户令牌（OAuth、个人 URL 或 Bearer 标头）建立的新会话会恢复这些信息，但前提是令牌已通过 API 验证。记忆保存在进程中，空闲 24 小时后过期，且绝不会保存用户令牌本身。还有两个默认设置可弥补同样的问题：ethora-app-create 会选中新应用；拥有且仅拥有一个应用的账户在首次调用应用范围内的工具时会自动选中该应用。

60 秒快速入门

Claude.ai 或 ChatGPT（自定义连接器）。 在 Ethora Web 应用中打开 Account，然后进入 AI Assistants 标签页，创建一个 API 密钥，并复制页面显示的个人连接器 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>"

Cursor、VS Code，以及任何支持 URL 和标头的客户端。

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

尚无账户的自主 Agent。 使用 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

然后让你的 Agent 调用 ethora-status、ethora-user-login（或 ethora-user-register）和 ethora-app-list。如果在任何一步不知所措，请调用 ethora-help：它会读取当前状态，并返回建议的后续调用。

入口点和身份验证

入口点	身份由谁提供	典型客户端
/mcp（添加 ?tools=all 可在一开始列出所有工具）	连接时无人提供。在会话中调用 ethora-user-login 或 ethora-user-register，或者在每个请求中发送 Authorization: Bearer <token>（用户 API 密钥、应用令牌或 B2B 令牌；服务会根据令牌类型选择身份验证模式）	Agent、Claude Code、Cursor，以及添加为“无需身份验证”的连接器
/mcp/k/<api-key>	路径中的密钥，其作用等同于 Bearer 请求头	Claude.ai 和 ChatGPT 自定义连接器，它们只接受 URL，不接受请求头
/mcp/oauth	通过 Ethora 授权服务获取的 OAuth 2.1 访问令牌（动态客户端注册、PKCE、访问范围 read、write、admin，以及需要这些范围的目录所需的身份范围 openid 和 email）	连接器目录（Claude、ChatGPT）；由供应商自行运行登录流程
stdio	环境变量 ETHORA_APP_JWT（用于登录／注册引导）和可选的 ETHORA_B2B_TOKEN，或在运行时调用 ethora-session-configure	本地 CLI

在托管服务上保持用户身份验证模式（ethora-status 显示 authMode: user）。应用令牌和 B2B 模式适用于服务集成；agents 和 rooms 路由不接受应用令牌。

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 Web 应用的 Account、AI Assistants 中管理；其中会显示个人 URL、Claude Code 单行命令和 Cursor 配置，并提供复制按钮。
• 密钥代表用户身份。请像保护密码一样保护个人 URL：不要分享其截图；如果泄露，请撤销密钥。服务绝不会记录请求 URL，且 monoserver nginx 模板在 MCP 主机上只记录方法和状态。

OAuth 2.1 (/mcp/oauth)

将 ETHORA_MCP_AUTH_ISSUER 设置为托管授权服务器的 Ethora API 公共 URL（monoserver 部署会设置此项）。随后，MCP 服务将：

• 在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-protected-resource/mcp/oauth 提供 RFC 9728 受保护资源元数据，注明授权服务器和三个作用域；
• 对 /mcp/oauth 上未经身份验证的请求返回 401 和 WWW-Authenticate: Bearer resource_metadata="..."，客户端通过此方式发现授权流程；
• 每个会话向 API 验证一次令牌（缓存五分钟），并根据工具强制执行令牌的 scope：只读工具需要 read；删除、撤销和轮换操作（以及显示凭据）需要 admin；其他所有操作，包括会覆盖字段、因此标记为破坏性的更新，都需要 write。search、fetch、ethora-help、ethora-status 和 ethora-doctor 不需要作用域。没有 scope 声明的令牌（API 密钥）可获得完整访问权限；
• 隐藏身份工具（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。用户可在“账户、AI 助手、已连接的 AI 应用”中查看并断开 OAuth 授权。当未设置 ETHORA_MCP_AUTH_ISSUER 时，两个 OAuth 路由都会返回 404，发现信息也不会包含它们。

身份作用域。 一些目录（ChatGPT）要求在 OAuth 2.1 基础上提供最精简的 OpenID Connect 功能：openid 和 email 作用域，以及一个返回 sub、email 和 email_verified 的 userinfo 端点。这些作用域不会授予对应用或数据的访问权限；它们只让客户端知道是谁登录了，授权页面也会用通俗的文字说明这一点。这里没有 ID 令牌或 JWKS，因为没有任何组件会使用它们。

电子邮件确认是可选的。 Ethora 绝不会因为地址尚未确认而阻止用户注册或访问仪表板。当客户端请求身份作用域，而账户地址尚未确认时，授权页面会增加一个步骤：发送确认链接、确认后继续，或者在不共享地址的情况下继续（身份作用域会从授权中移除，其他流程照常进行）。通过 Google 登录的地址已确认，因此会跳过此步骤。也可以在 Web 应用的“账户、AI 助手”中发送相同的确认邮件。

Agent 能做什么

新用户通常会按以下顺序完成端到端流程：

1. 使用 ethora-user-register（或 ethora-user-login）获取经过身份验证的会话和 API 密钥。
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 Agent 角色。
5. 使用 ethora-agent-invite { agentIdOrAddress, chatJid } 将 Agent 加入房间。系统会实时生成一个机器人实例，无需重启。
6. 使用 ethora-message-send { text, roomJid, waitForReplySec: 45 } 发送消息并等待 Agent 回复，回复会通过 replies 返回。之后可使用 ethora-chat-history 读取房间内容。
7. 使用 ethora-agent-activate { agentId, chatJid } 将该 Agent 设为应用的默认响应者，然后使用 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 可执行这些方案。

入门首分钟约定

• 所有创建工具的响应方式相同。 ethora-app-create、ethora-chat-create、ethora-agent-create 会返回原始 API 对象，以及 created（包含 kind、id、name，以及相关的 jid 或 address）和 next（包含两到四个已填入参数的建议调用）。ethora-app-create 还会返回 dashboardUrl，即 Web 控制面板中的应用页面。
• 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），因此多 Agent 房间会显示为“弗洛伊德：……，荣格：……”，而非实例 ID。
• 搜索能理解意图。 search 会将用户常用的说法（“将聊天添加到我的 React 应用”“多个 Agent 互相对话”“收到消息时触发 webhook”）映射到相关文档；doc:not-available 会明确说明哪些内容未通过 MCP 暴露，以及这些内容位于何处。可通过裸 ID 获取完整文档（doc:recipes、doc:chat-component-quickstart、doc:sdk-backend-quickstart、doc:auth-map）。

服务内的文档

• 初始化结果中的 instructions 会告知助手其所连接入口的身份验证方式：开放端点会说明登录和注册流程；使用个人 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 个工具，覆盖“登录、创建应用、添加房间和消息、创建并激活 Agent、为其提供知识库、获取小组件”的完整流程，每种操作各有一个变体。其他组已注册，但处于隐藏状态，这使 tools/list 的大小保持在约 40 KB，而非 120 KB，并为助手提供一个较短的工具列表供其选择。

有三种方式可以获取更多工具：

• ethora-tools-enable { group } 可为会话启用一个组（或使用 { group: "all" }）；服务会发送 tools/list_changed，客户端随后刷新。不带参数调用时，它会返回包含数量统计的目录。
• 按名称调用隐藏工具会启用其所属组并运行该工具，因此从文档或之前的会话中获知的名称永远不会被拒绝。
• 在端点 URL 中添加 ?tools=all（托管模式），或设置 ETHORA_MCP_TOOLS=all（stdio），即可一开始就列出所有工具。

search 和 fetch 也会介绍隐藏工具；每个工具文档都会注明其所属组，而 doc:tool-groups 是工具目录。旧版和异步变体的首行会标明其优先使用的同级工具。

分组	涵盖内容	工具
core（默认列出）	登录或注册、创建应用、添加聊天室和消息、创建并激活 AI Agent、为其配置知识库、获取网站小组件。始终列出。	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	查看、克隆（含或不含其知识库）、删除、导出和导入 Agent；在没有聊天室的情况下试用 Agent；检查并重建其知识索引；编辑其记忆和可见性。	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	查看和更改已保存的网站小组件外观（颜色、字体、大小、启动器、预告语、文本）；在线嵌入会自动应用更改，无需获取新代码片段。	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	适用于在 Agent 框架推出前通过仪表板创建的应用的单应用机器人，以及 v2 之前的文档工具。新任务请优先使用 Agent 和资源工具。	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 时，才会注册应用删除和批量删除工具（单体服务部署会设置此变量；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 分组），与管理面板中“应用设置”>“AI 小组件”的设置相同。每次打开嵌入的小组件时都会加载这些设置，因此之后的更改无需更新代码片段即可应用到正在运行的网站。在该网站的标签上设置的 data-* 属性优先于已保存的值。

小组件使用应用当前激活的机器人（defaultBotInstanceId）作答。对于通过 API 创建的应用，请先运行 ethora-agent-create、ethora-chat-create、ethora-agent-invite 和 ethora-agent-activate { agentId, chatJid }；该工具会列出这些前置条件，ethora-help { goal: "widget" } 则会引导你完成设置。激活操作会在用户身份验证下执行，方法是设置应用的默认机器人实例（即管理面板中“AI 小组件”下拉菜单所执行的操作）。激活机器人之前，小组件的会话端点会返回 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 应用门户签发的域名验证令牌；会原样提供在 /.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；该值会转发到 API，以便按调用方应用每 IP 限制
ETHORA_MCP_SESSION_TTL_MS	空闲会话清除时间，默认为 4 小时
ETHORA_MCP_ACCOUNT_MEMORY_TTL_MS	账户记忆上下文（当前应用、Agent、启用的群组）在没有会话时保留的时长，默认为 24 小时
ETHORA_MCP_AUTH_ISSUER	OAuth 授权服务器的公共 URL（Ethora API 主机）；启用 /mcp/oauth
ETHORA_MCP_WIDGET_URL	托管式 AI 聊天组件的基础 URL（<url>/assistant.js），供 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 和一行提示。

与 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 Agent 模式）

.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

设置、开发者、编辑配置（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 可通过一次调用创建应用、为来源建立索引（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 和 widget 路由
widget 返回 AI_BOT_NOT_CONFIGURED	应用没有活动机器人。运行 Agent，然后完成邀请和 ethora-agent-activate 步骤，最后重新加载页面
ethora-bot-* 返回 BOT_NOT_INITIALIZED (422)	应用没有旧版的逐应用机器人；请改用 agents 工具
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 会在会话中向 Ethora 团队发送报告（bug、unexpected、feature、docs、other）。通过 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-key / app-token 的工具仍会按设计返回一次凭据。

• API 密钥和个人 URL 在撤销前都可以代表用户执行操作。请将它们保存在客户端的密钥存储中，切勿放入共享配置或屏幕截图中；如有泄露嫌疑，请撤销。

• 服务端绝不记录请求 URL 或令牌。请确保反向代理的访问日志不记录 MCP 主机的请求路径（monoserver nginx 模板已作此处理）。

• 工具返回的所有内容都对模型可见，并会存储在对话记录中；服务端会告知助手不要打印密钥或密码，并在使用破坏性工具前向用户确认。

• 此仓库会在推送和 PR 时运行仅报告结果的密钥和 SAST 扫描（gitleaks、semgrep）。

开发

版本号

版本采用日历编号：YY.M.patch，其中 YY.M 表示版本发布的年月（26.9.5 是 2026 年 9 月发布的第五个版本，26.10.0 是 10 月发布的第一个版本），patch 表示该月内的发布次数。月份不带前导零，因此按 semver 排序时，26.10 会排在 26.9 之后。破坏性变更不会递增主版本号；它们会使用下一个 patch 版本，并在变更日志中记录，较早的工具名称仍可作为别名调用。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 是单数名词，由一个或两个词组成：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 都已移除。按照 ChatGPT 连接器惯例，search 和 fetch 保留原名。

所有旧名称仍然有效。 旧名称会作为别名：它们不会由 tools/list 列出，但调用旧名称时会被改写为规范工具（如果三个或两个工具合并为一个，则会预设参数，例如 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.