@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "MCP客户端"
+description: "将您的代理本机应用程序连接到本地 MCP 服务器（claude-in-chrome、文件系统、剧作家等），以便代理获得其工具。"
+---
+
+# MCP客户端
+
+**此页面：为您的代理提供更多工具。** 将代理本机应用程序指向 MCP 服务器（本地或远程），以便他们的工具显示在代理聊天中。这是 _client_ 方向，[MCP Protocol](/docs/mcp-protocol) 的镜像（这使您的应用成为 MCP _server_）。
+
+| 如果你想……                                              | 阅读                                     |
+| ------------------------------------------------------- | ---------------------------------------- |
+| 将外部代理/主机连接到您的应用                           | [External Agents](/docs/external-agents) |
+| 为您的代理提供更多工具（使用其他 MCP 服务器）           | **此页面** — MCP 客户端                  |
+| 构建在 Claude/ChatGPT 中渲染的内联 UI                   | [MCP Apps](/docs/mcp-apps)               |
+| 较低级别的 MCP 服务器参考（身份验证、工具、自定义挂载） | [MCP Protocol](/docs/mcp-protocol)       |
+
+通过一个配置文件，工作区中的每个代理本机应用都可以访问计算机上的 MCP 服务器提供的工具：用于浏览器自动化的 `claude-in-chrome`、用于读取文件的 `@modelcontextprotocol/server-filesystem`、用于浏览器测试的 `@playwright/mcp` 以及任何使用 MCP 的其他工具。
+
+您还可以 [connect remote (HTTP) MCP servers at runtime](#remote-via-ui)（个人用户或整个组织），而无需编辑配置文件。
+
+每个源都会解析为一个运行时 **MCP 管理器**，并且它学习的每个工具都会以防碰撞 `mcp__<server-id>__<tool>` 前缀登录到代理的工具注册表中 - 可通过 `tool-search` 进行意图搜索。
+
+```an-diagram title="Client direction: many sources, one tool registry" summary="Config files, env, and runtime UI all merge into the MCP manager; its tools appear prefixed and tool-searchable alongside your app's actions. This is the mirror of the server direction."
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">shared across apps</small></div><div class=\"diagram-box\" data-rough>App-root <code>mcp.config.json</code><br><small class=\"diagram-muted\">per-app override</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / production</small></div><div class=\"diagram-box\" data-rough>Remote via settings UI<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP manager</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent tool registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">discover by intent</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> 相反的方向 - 使 _your_ 应用程序成为其他主机使用的 MCP 服务器 - 位于 [MCP Protocol](/docs/mcp-protocol) 和 [External Agents](/docs/external-agents) 中。
+
+## 内置浏览器和计算机使用功能 {#built-in-capabilities}
+
+Agent-native 包括常见 stdio MCP 服务器的本地开发切换。
+默认情况下它们处于关闭状态，并且只能针对每个用户或每个组织启用
+当应用程序在本地运行时。跳过生产和托管无服务器运行时
+即使旧设置行存在，这些内置函数和工作区资源
+树不会将它们显示为默认的 `mcp-servers/*.json` 资源。
+
+| 能力            | 服务器 ID         | 命令                                                                    |
+| --------------- | ----------------- | ----------------------------------------------------------------------- |
+| Chrome 开发工具 | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| 剧作家浏览器    | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| 计算机使用      | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+一次只能在一个范围内启用一种浏览器功能。启用 Chrome DevTools 会禁用同一用户或组织的 Playwright，启用 Playwright 会禁用 Chrome DevTools。
+
+计算机使用仅限 macOS。在其他平台上，它被列为不可用，并且即使旧设置行包含它也会被跳过。
+
+Chrome DevTools 默认使用 `--autoConnect`。它附加到符合条件的正在运行的 Chrome 实例；它不会为您创建独立的浏览器配置文件或登录用户的常规配置文件。它需要启用远程调试的 Chrome 144+。当部署需要特定的调试端点时，可以稍后添加手动 `browser-url` 配置。
+
+内置程序保留在框架的 `settings` 表中，位于用于个人切换的 `u:<email>:mcp-builtin-capabilities` 和用于团队切换的 `o:<orgId>:mcp-builtin-capabilities` 下。启用后，它们会合并到运行时 MCP 管理器中，其范围可见性格式与远程服务器相同，例如 `mcp__user_<emailhash>_playwright__*` 或 `mcp__org_<orgId>_chrome-devtools__*`。
+
+### 面向用户的设置说明
+
+对敏感的内置程序使用简洁、明确的设置副本：
+
+- **Chrome DevTools** 附加到正在运行的 Chrome 调试目标。告诉用户
+  它用于浏览器测试和登录验证，并且它
+  可能需要在工具出现之前启用 Chrome 远程调试。
+- **Playwright** 启动一个独立的浏览器。推荐它用于确定性
+  当不需要用户的实时 Chrome 个人资料时进行质量检查。
+- **计算机使用**可以操作本地应用程序。默认关闭，解释一下
+  macOS 屏幕录制和辅助功能提示，并在拍摄前询问
+  敏感的 actions，例如购买、财务变化或帐户更改。
+
+### 内置端点
+
+| 方法 | 路线                         | 目的                                                                  |
+| ---- | ---------------------------- | --------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/builtin` | 列出内置功能、启用的范围、合并的 ID 和实时状态。                      |
+| POST | `/_agent-native/mcp/builtin` | 更新范围。主体：`{ scope, enabledIds }` 或 `{ scope, id, enabled }`。 |
+
+## 添加本地MCP服务器 {#adding-a-server}
+
+在您的工作区根目录（或单个应用程序根目录 - 当两者都存在时，工作区根目录获胜）创建 `mcp.config.json`：
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+形状很小：由服务器 ID 键入的 `servers` 映射，其中每个条目都是 stdio 启动器（`command` + `args` + 可选的 `env`）或远程 `{ "type": "http", "url", "headers" }` 条目。
+
+```an-annotated-code title="mcp.config.json, annotated"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "Server id", "note": "The key becomes the tool prefix: this server's tools surface as `mcp__claude-in-chrome__*` in the agent's registry, so they can't collide with your template's actions." },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` spawn a local binary. Stdio servers are intended for **local development** — they are a no-op in edge runtimes." },
+    { "lines": "6", "label": "Process env", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+在下一次应用程序启动时，您将看到：
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+这些工具在代理的工具注册表中注册，前缀为 `mcp__<server-id>__<tool-name>`，因此它们不会与模板的 actions 发生冲突。它们也包含在 `tool-search` 中，因此代理可以通过意图发现新连接的 MCP 功能，而不需要预先提供确切的前缀名称。
+
+## 配置优先级 {#precedence}
+
+MCP 配置按此顺序解析，第一个匹配获胜：
+
+1. **工作空间根 `mcp.config.json`** — 通过 `package.json` 中的 `agent-native.workspaceCore` 检测到。在工作区中的每个应用程序之间共享。
+2. **应用程序根 `mcp.config.json`** — 如果您不希望每个应用程序中都提供 MCP 服务器，则按应用程序覆盖。
+3. **`MCP_SERVERS` env var** — 具有相同形状的 JSON 字符串，适用于文件没有意义的 CI/生产。
+
+## 生产部署：`MCP_SERVERS` {#mcp-servers-env}
+
+对于生产部署，首选远程 HTTP MCP 服务器并设置完整配置
+形状（或内部服务器映射）作为环境变量：
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` 被解析为 JSON，因此 `${...}` 占位符不会扩展
+在字符串内。如果您将令牌存储在另一个秘密中，请先将其展开
+写入最终的 JSON 值。
+
+Stdio MCP 服务器生成本地二进制文件，用于本地开发。
+MCP 工具仅在 Node 运行时激活 - Cloudflare Workers 和其他边缘
+目标默默地跳过 MCP 并继续应用程序的其余部分工作
+通常。
+
+## 自动检测：`claude-in-chrome` {#autodetect}
+
+如果您**没有** `mcp.config.json` 并且 `claude-in-chrome-mcp` 二进制文件位于 `PATH`（或众所周知的安装位置 `~/.claude-in-chrome/bin/claude-in-chrome-mcp`）上，则本机代理会将其自动注册为默认 MCP 服务器。将 `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` 设置为选择退出。
+
+这意味着安装了 claude-in-chrome 扩展程序的用户无需更改配置即可获得对他们打开的每个代理本机应用程序的浏览器控制。
+
+## 通过设置 UI 远程 MCP 服务器 {#remote-via-ui}
+
+MCP（模型上下文协议）服务器为您的代理提供新的能力 - 例如连接到 Zapier、Cloudflare、Composio 或您公司的内部工具。连接后，代理可以像使用内置工具一样使用这些工具。
+
+### 如何连接远程MCP服务器
+
+1. **服务器名称** - 供您自己参考的简短标签（例如“zapier”、“slack-tools”）。
+2. **URL** — MCP 服务器提供商为您提供的 HTTPS 端点（例如 `https://mcp.zapier.com/s/abc123/mcp`）。这通常可以在提供商的仪表板或集成文档中找到。
+3. **描述**（可选）- 关于此服务器功能的注释。
+4. **标头** — 服务器所需的身份验证凭据，每行一个。大多数服务器需要 `Authorization` 标头。示例：`Authorization: Bearer sk-your-key-here`。提供商的文档会告诉您在此处放置什么内容。
+
+单击“**测试**”以在保存之前验证连接。如果成功，您将看到可用工具的数量。单击“**连接**”进行添加。
+
+### 个人与组织范围
+
+支持两个范围：
+
+- **个人** — 只有登录用户才能获得工具。存储为用户范围设置。
+- **团队** — 活跃组织中的每个人都可以获得工具。所有者和管理员可以添加；成员只能看到该列表。存储为组织范围设置。
+
+在正在运行的 MCP 管理器中添加和删除热重载 — 无需重新启动进程，也无需重新启动服务器。新的 `mcp__<scope>-<name>__*` 工具将在下一条消息中向客服人员显示，并且可通过 `tool-search` 进行搜索。
+
+HTTPS URL 在任何地方都被接受； plain `http://` 在开发过程中仅允许用于 `localhost`。可选的身份验证作为不记名令牌在每个请求上通过 `Authorization: Bearer …` 发送。
+
+在底层，这些服务器以 `u:<email>:mcp-servers-remote`（个人）或 `o:<orgId>:mcp-servers-remote`（团队）键保存在框架的 `settings` 表中，并在启动时与 `mcp.config.json` 合并。
+
+### HTTP端点
+
+| 方法   | 路线                                                  | 目的                                                               |
+| ------ | ----------------------------------------------------- | ------------------------------------------------------------------ |
+| GET    | `/_agent-native/mcp/servers`                          | 列出当前用户的个人+组织服务器的实时状态。                          |
+| POST   | `/_agent-native/mcp/servers`                          | 添加服务器。身体：`{ scope, name, url, headers?, description? }`。 |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                       |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                |
+| POST   | `/_agent-native/mcp/servers/test`                     | 在持久化之前试运行任意 URL。机身：`{ url, headers? }`。            |
+
+Stdio 服务器在 Node 运行时之外仍然是无操作的，但远程 HTTP MCP 服务器可以在任何具有 `fetch` 的环境中工作 - 包括桌面生产版本。
+
+## 通过集线器共享 MCP 服务器 {#hub}
+
+如果您的工作区运行多个代理本机应用程序（例如调度+邮件+剪辑），您可以将**一个**应用程序配置为中心，并让其他应用程序自动拉取其组织范围的MCP服务器。没有每个应用程序复制粘贴 URL 和不记名令牌。请参阅 [Multi-App Workspace](/docs/multi-app-workspace) 了解使用 Dispatch 工作区 MCP 资源的规范方法。
+
+Dispatch 是传统的中心 - 它已经跨应用进行协调。
+
+```an-diagram title="Hub model: one app serves org-scope MCP servers" summary="Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">org-scope MCP servers</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">pull + merge each ~60s</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+对于新的工作区设置，首选\*\*在您
+想要工作区 skills 使用相同的全应用与选定应用授权模型，
+说明和参考资源。添加工作区资源：
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+将其保存在 `mcp-servers/<name>.json` 下，类型为 `mcp-server`。所有应用
+资源由每个工作区应用程序加载；选定的资源仅加载
+具有有效调度授权的应用程序。从应用程序解析秘密占位符
+秘密存储，因此将原始不记名令牌放入 Dispatch Vault 并引用它们
+使用 `${keys.NAME}`，而不是将它们存储在资源主体中。
+
+应用程序大约每分钟刷新一次合并的 MCP 配置，因此是中央资源
+编辑、授予更改和删除无需部署即可生效。设置
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` 禁用后台刷新，或
+将其设置为至少 `5000` 毫秒的值以调整间隔。
+
+下面的旧集线器模式对于粗略的“共享每个组织范围 MCP”仍然有用
+来自 Dispatch 的服务器”设置以及已使用 MCP 的部署
+将 UI 设置为事实来源。
+
+### 1。在集线器应用程序上启用集线器服务（调度）
+
+在调度的部署中设置环境变量：
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch 现在挂载 `GET /_agent-native/mcp/hub/servers`，它返回存储在其 `settings` 表中的每个组织范围 MCP 服务器，以及完整的 URL + 标头，并通过令牌进行身份验证。
+
+### 2。将消费应用程序指向中心
+
+对每个消费者进行设置（邮件、剪辑等）：
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+启动时，每个消费者都会拉取集线器的服务器列表并将其合并到自己的 MCP 管理器中。这些工具对代理来说显示为 `mcp__hub_<orgId>_<name>__*` — 与消费者自己的本地 `mcp__org_…` 不同，因此不会发生冲突。
+
+### 3。分享什么内容
+
+仅共享**组织范围**服务器。用户范围（个人）服务器由添加它们的用户保留 - 中心绝不会跨应用程序重新公开个人凭据。
+
+集线器响应包括完整的身份验证标头（承载令牌等）。传输是 HTTPS，端点需要共享密钥，并且它仅返回组织范围行 - 将中心 URL + 令牌视为数据库凭证。
+
+### 4。热重载与重启
+
+本地 UI 通过 `McpClientManager.reconfigure()` 在每个应用程序中添加热重载 - 无需重新启动。集线器来源的服务器由工作区资源路径使用的相同定期后台刷新（大约 60 秒，可通过 `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS` 调整或禁用）来获取，因此在 Dispatch 中所做的更改会在大约一分钟内传播到所有消费者应用程序，而无需重新启动。此外，消费者应用程序中的任何本地突变都会立即触发该应用程序的重新配置。
+
+### 端点摘要
+
+| 方法 | 路线                             | 目的                                                                                               |
+| ---- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/hub/servers` | 为所有组织范围的服务器提供完整的信用（不记名门控，仅在设置 `AGENT_NATIVE_MCP_HUB_TOKEN` 时安装）。 |
+| GET  | `/_agent-native/mcp/hub/status`  | 返回设置UI卡的`{ serving, consuming, hubUrl }`。                                                   |
+
+## 状态路线 {#status-route}
+
+每个应用程序都公开 `GET /_agent-native/mcp/status` 用于工具和入门：
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP client status for tooling and onboarding",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+使用它来构建“检测到 claude-in-chrome - 您的代理现在可以驱动 Chrome”入门提示，或调试 MCP 连接问题。
+
+## 故障模式 {#failures}
+
+个别 MCP 服务器故障永远不会导致代理关闭：
+
+- 配置错误的 `command` → 服务器被跳过，其错误出现在 `errors.<server-id>` 下的 `/mcp/status` 中，而其他所有服务器继续工作。
+- `node_modules` 中缺少 MCP SDK → 所有 MCP 功能都会被跳过并出现警告；代理聊天可以使用零 MCP 工具继续工作。
+- 在边缘运行时中运行 → MCP 客户端是无操作的。
+
+代理本机将始终启动；损坏的 MCP 配置仅意味着工具更少。
+
+## 安全 {#security}
+
+MCP 工具在您的计算机上运行，具有生成的进程具有的任何权限。像对待您愿意让代理驱动的任何其他可执行文件列表一样对待 `mcp.config.json`。来自 MCP 服务器的工具出现在代理的工具使用循环中，就像您模板自己的 actions 一样，因此请确保您信任您配置的每个服务器。

package/corpus/core/docs/content/locales/zh-CN/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "MCP协议"
+description: "将您的代理原生应用公开为远程 MCP 服务器，以便 Claude、ChatGPT、Claude 代码、光标和其他 AI 工具可以直接调用您应用的 actions。"
+---
+
+# MCP协议
+
+**此页面：较低级别的 MCP 服务器参考。** 每个代理本机应用程序如何通过 MCP 公开其 actions — 自动安装的端点、身份验证模式、`tools/call` / `ask-agent` 表面和自定义安装。当您需要服务器内部结构时，可以使用它；要连接主机，请从 [External Agents](/docs/external-agents) 开始。
+
+| 如果你想……                                              | 阅读                                     |
+| ------------------------------------------------------- | ---------------------------------------- |
+| 将外部代理/主机连接到您的应用                           | [External Agents](/docs/external-agents) |
+| 为您的代理提供更多工具（使用其他 MCP 服务器）           | [MCP Clients](/docs/mcp-clients)         |
+| 构建在 Claude/ChatGPT 中渲染的内联 UI                   | [MCP Apps](/docs/mcp-apps)               |
+| 较低级别的 MCP 服务器参考（身份验证、工具、自定义挂载） | **此页** — MCP 协议                      |
+
+每个代理本机应用程序都会自动公开远程 MCP（模型上下文协议）服务器，因此 Claude、ChatGPT 自定义 MCP 应用程序、Claude Code、Cursor、Codex 和 VS Code GitHub Copilot 等外部 AI 工具可以直接发现并调用应用程序的 actions - 无需额外代码需要。如果您的目标是将其中一台主机连接到托管应用程序，[External Agents](/docs/external-agents) 涵盖建议的单个调度连接器、每个应用程序 URL、OAuth、MCP 应用内联 UI 和深层链接。此页面记录了其下方的内容。
+
+## 概述 {#overview}
+
+MCP 是用于将 AI 工具连接到外部功能的标准协议。当您部署代理本机应用程序时，它会自动安装 MCP 端点以及现有的 A2A 端点。任何与 MCP 兼容的客户端都可以连接并使用您应用的工具。
+
+关键概念：
+
+- **自动安装** — 每个应用都免费获得 `/_agent-native/mcp`，无需设置
+- **Streamable HTTP** — 在标准 HTTP (POST + SSE) 上使用现代 MCP 传输
+- **相同的 actions** — 为代理聊天和 A2A 提供支持的完全相同的操作注册表
+- **`ask-agent` 工具** — 一种元工具，可委托给完整代理循环来执行复杂任务
+- **MCP 应用程序** — actions 可以通过官方 `io.modelcontextprotocol/ui` 扩展来宣传交互式 UI 资源
+- **标准远程 MCP OAuth** — OAuth 2.1 发现、动态客户端注册、授权代码 + PKCE、刷新令牌轮换
+- **承载身份验证回退** - 对于无法运行 OAuth 的客户端使用 `ACCESS_TOKEN`、`ACCESS_TOKENS` 或 connect-minted JWT
+
+```an-diagram title="Your app as an MCP server" summary="External hosts connect over Streamable HTTP. Each action is one tool; ask-agent delegates to the full agent loop."
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP vs A2A {#mcp-vs-a2a}
+
+两种协议都是自动安装的。使用适合您的用例的选项：
+
+|              | MCP                                                                 | A2A                                    |
+| ------------ | ------------------------------------------------------------------- | -------------------------------------- |
+| **最适合**   | 调用您的应用的外部工具                                              | 代理间通信                             |
+| **协议**     | MCP 可流式传输 HTTP                                                 | JSON-RPC 2.0                           |
+| **工具发现** | `tools/list`                                                        | `/.well-known/agent-card.json`的代理卡 |
+| **端点**     | `/_agent-native/mcp`                                                | `/_agent-native/a2a`                   |
+| **支持**     | Claude、ChatGPT、Claude Code、Cursor、Codex、Cowork 和其他 MCP 主机 | 其他代理本机应用                       |
+| **执行**     | 直接工具调用（无需额外的LLM）                                       | 完整代理循环（LLM 推理）               |
+
+您还可以使用 `ask-agent` MCP 工具来获得两全其美的效果 - 从 Claude 代码中调用它，并让您的应用的代理通过复杂的任务进行推理。
+
+## 手动 MCP 客户端配置 {#manual-config}
+
+对于建议的单命令设置，请使用 [External Agents](/docs/external-agents)。如果您为支持 OAuth 的客户端手写 MCP 配置，请将您的应用添加为不带静态标头的远程 MCP 服务器：
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+或者在 `.mcp.json`（项目范围）或 `~/.claude.json`（用户范围）中手动写入条目：
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+然后在Claude代码中运行`/mcp`并选择**验证**。对于无法执行远程 MCP OAuth 的客户端，请使用“连接”页面或带有 `headers.Authorization` 的静态承载令牌条目。经过身份验证后，您可以自然地使用应用程序的工具：
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## 从其他MCP客户端连接 {#other-clients}
+
+任何支持 Streamable HTTP 传输的 MCP 客户端都可以连接。端点是：
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+服务器支持标准MCP握手：`initialize`→`initialized`→`tools/list`→`tools/call`。
+
+```an-api title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes."
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP Streamable HTTP endpoint",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+如果操作声明 `mcpApp`，服务器还会通告官方 MCP 应用扩展 (`io.modelcontextprotocol/ui`)，并支持应用资源的 `resources/list`、`resources/templates/list` 和 `resources/read`。渲染 MCP 应用程序的主机可以内联显示 UI；不这样做的主机仍然可以调用该工具并使用深层链接后备。产品 UI 应使用 `embedApp()`，因此内联表面是真正的 React 应用程序路由，或者呈现共享 React 组件（例如 Analytics 图表）的集中路由，而不是单独的普通 HTML 实现。服务器发出标准 MCP 应用元数据和 ChatGPT 应用 SDK 兼容性元数据，以便支持应用程序的主机可以找到相同的 `ui://` 资源。目前官方扩展矩阵包括Claude、Claude Desktop、VS Code GitHub Copilot、Goose、Postman、MCPJam、ChatGPT、Cursor；主机支持因版本和计划而异，因此请使用 [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) 来获取面向用户的指导。
+
+### MCP 应用嵌入桥 {#mcp-app-embed-bridge}
+
+`embedApp()` 是低级 URL-first MCP 应用程序助手：它启动签名的应用程序
+通过移植 (Claude)、受控帧 (ChatGPT) 或直接进行内联路由
+导航，通过 `ui/*` JSON-RPC 桥（以及
+`agentNative.mcpHost.*` postMessage 中继用于受控帧路径），以及
+限制资源外壳高度，因此完整应用程序路由不会呈现为
+超大的聊天神器。
+
+有关完整嵌入桥的详细信息，请参阅 [MCP Apps](/docs/mcp-apps#mcp-app-bridge) - 移植与受控框架、`ui/*` 和 postMessage 表、`create_embed_session` / `embedStartUrl`、CSP 和域规则、扩展 `srcDoc` 嵌入、高度限制和主桥客户端 API。
+
+## 工具 {#tools}
+
+每个调用者默认都会获得一个**紧凑目录**（模板声明的应用程序 actions 加上跨应用程序内置），完整的操作界面仅在明确选择加入时提供，并且 `tool-search` 始终可用于到达其余部分。完整解释请参见 [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers)。
+
+每个操作都直接映射到一个 MCP 工具：
+
+| 操作属性           | MCP工具属性   |
+| ------------------ | ------------- |
+| `tool.description` | `description` |
+| `tool.parameters`  | `inputSchema` |
+| 操作名称           | 工具名称      |
+
+当存在`mcpApp`时，工具条目还包括`_meta.ui.resourceUri`、`_meta["ui/resourceUri"]`和`_meta["openai/outputTemplate"]`，并且相应的`ui://`资源返回为`text/html;profile=mcp-app`。
+
+### `ask-agent` 工具 {#ask-agent}
+
+除了单独的操作工具外，每个 MCP 服务器还包含一个 `ask-agent` 元工具。这会向应用程序的 AI 代理发送一条自然语言消息并返回响应。
+
+使用 `ask-agent` 执行复杂任务，受益于代理的推理和上下文：
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+代理运行与交互式聊天相同的循环 - 它可以调用多个工具、推理上下文并生成深思熟虑的响应。
+
+## 身份验证 {#authentication}
+
+MCP 端点支持标准远程 MCP OAuth 以及现有的不记名令牌后备：
+
+| 模式                 | 它是如何工作的                                                                                       |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| 标准MCP OAuth        | 客户端从`WWW-Authenticate`发现身份验证，注册，运行PKCE，并发送`Authorization: Bearer <access-token>` |
+| 连接铸造JWT          | `npx @agent-native/core@latest connect` / Connect 页面铸造一个每用户、可撤销的 JWT                   |
+| `ACCESS_TOKEN`       | 静态不记名令牌 - 客户端发送 `Authorization: Bearer <token>`                                          |
+| `ACCESS_TOKENS`      | 以逗号分隔的有效静态不记名令牌列表                                                                   |
+| `A2A_SECRET`         | 基于 JWT 的身份验证 - 令牌通过加密方式进行验证                                                       |
+| _（未设置，仅环回）_ | 本地开发探针不需要身份验证                                                                           |
+
+对于支持 OAuth 的 MCP 主机，配置不带静态标头的远程服务器 URL：
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+第一个未经身份验证的 MCP 请求收到：
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+发现端点：
+
+| 端点                                      | 目的                      |
+| ----------------------------------------- | ------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 受保护资源元数据 |
+| `/.well-known/oauth-authorization-server` | OAuth 授权服务器元数据    |
+| `/_agent-native/mcp/oauth/register`       | 动态公共客户端注册        |
+| `/_agent-native/mcp/oauth/authorize`      | 浏览器授权+同意           |
+| `/_agent-native/mcp/oauth/token`          | 授权代码和刷新令牌授予    |
+
+```an-diagram title="OAuth discovery flow" summary="A 401 kicks off discovery, registration, and a PKCE authorize → token exchange. The Bearer token is audience-bound and scoped."
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">audience-bound · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+访问令牌是经过签名的 JWT，其受众是确切的 MCP 资源 URL。服务器仅接受为其自身颁发的令牌，并在列出/调用工具之前应用范围：
+
+| 范围        | 允许                              |
+| ----------- | --------------------------------- |
+| `mcp:read`  | 只读 actions                      |
+| `mcp:write` | 突变 actions 和 `ask-agent`       |
+| `mcp:apps`  | MCP 应用资源（`ui://` HTML 资源） |
+
+刷新令牌仅存储为哈希值，并在每次刷新时轮换。默认情况下，`npx @agent-native/core@latest connect` 为 Claude 代码客户端写入仅 URL 的 OAuth 条目；保留连接页面、`npx @agent-native/core@latest connect --token <token>` 和静态承载配置以用于本地 stdio 代理、旧客户端和紧急/调试流程。
+
+## 自定义 MCP 设置 {#custom-setup}
+
+MCP 服务器由代理聊天插件自动安装。对于大多数应用程序，无需配置。如果您需要自定义行为，您可以在服务器插件中手动安装它：
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## 示例：来自 Claude 代码的分析 {#example}
+
+您在 `analytics.example.com` 部署了分析应用程序。来自Claude代码：
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+或者在`.mcp.json`中手动添加：
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+现在在 Claude 代码中：
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+对于更复杂的分析：
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```