| 1 | # MCP（外部工具服务器） |
| 2 | |
| 3 | > 本文翻译自英文版 [MCP.md](../MCP.md)，与英文修订 `4d915398f`（2026-08-19）同步。 |
| 4 | |
| 5 | codewhale 可以通过 MCP（Model Context Protocol，模型上下文协议）加载额外工具。MCP 服务器可以是 TUI 启动的本地 stdio 进程，也可以是使用 Streamable HTTP（带传统 SSE 回退）的远程基于 URL 的服务器。 |
| 6 | |
| 7 | 浏览说明： |
| 8 | - `Web` 是规范的、延迟加载的内置浏览工具；在网络策略允许时，它提供 `search`、`fetch` 和 `wait` 操作。 |
| 9 | - `web_search`、`fetch_url` 和 `wait_for_dev_server` 是隐藏的仅回放别名。新的提示和集成应使用 `Web`。 |
| 10 | |
| 11 | 服务器模式说明： |
| 12 | - `codewhale-tui serve --mcp` 运行 MCP stdio 服务器。 |
| 13 | - `codewhale-tui serve --http` 运行运行时 HTTP/SSE API（独立模式）。 |
| 14 | - `codewhale` 调度器将 `codewhale mcp-server` 作为等价的 stdio 入口点暴露出来，供独立分发的 CLI 使用。 |
| 15 | |
| 16 | ## 设置向导与手动 MCP 设置（#3407） |
| 17 | |
| 18 | `/setup` 中心包含一个可选的 **Tools and MCP** 步骤。该步骤仅用于发现/就绪检查： |
| 19 | |
| 20 | | 向导可以做的 | 仍然需要手动/显式操作 | |
| 21 | | --- | --- | |
| 22 | | 将已配置的服务器显示为 `healthy` / `needs_config` / `off` | 启动或连接 MCP 服务器 | |
| 23 | | 报告配置路径是否存在（全局 + 项目） | 写入或编辑 `mcp.json` 内容 | |
| 24 | | 安全的静态健康探测（缺少 command/url、损坏的绝对路径、缺少 bearer 环境变量） | `codewhale mcp validate`、实时连接、OAuth 登录 | |
| 25 | | 指向安全的入门路径（`/mcp`、`codewhale mcp init`、`codewhale doctor`） | 安装社区技能、信任技能、启用插件 | |
| 26 | | 共享来自同一 skill/MCP 适配器的 Hotbar 来源计数（#3399） | 绑定 Hotbar 槽位（Hotbar 步骤 / `H`） | |
| 27 | | 记录可选的/`needs_action` setup_state，不阻塞首次运行 | 任何会生成进程或安装包的操作 | |
| 28 | |
| 29 | 空清单**不是**错误：首次运行的用户会看到"尚未配置任何内容，这没关系。"失败或不完整的已配置服务器会以 `needs_config` 状态显示，并附带可操作的提示，绝不会阻塞设置完成。枚举过程除静态探测外，绝不执行 MCP/插件命令。摘要会隐去命令、参数、环境变量、请求头和令牌。 |
| 30 | |
| 31 | `codewhale doctor` 以相同的可选表面意图（路径、计数、静态检查）报告 MCP/技能/工具/插件的健康状态，使向导与 doctor 保持一致。 |
| 32 | |
| 33 | ## 插件贡献的 MCP |
| 34 | |
| 35 | 通过审查的本地插件包可以贡献 MCP 服务器，而无需创建第二套传输或审批系统。这些服务器使用本文档记载的同一条 MCP 管理器、工具审批、资源、提示、超时和网络策略路径，并以命名空间化的 `<plugin>-<server>` 身份出现。 |
| 36 | |
| 37 | 插件包边界有意比用户编写的 `mcp.json` 更严格：未知字段和模糊的传输方式默认失败关闭；stdio 环境变量值必须是精确的环境来源引用；远程字面量请求头和含机密信息的 URL 会被拒绝；声明的网络主机必须与规范化后的端点主机集合完全匹配；重定向保持在已审查的源站内。已审查的插件远程端点还会完全绕过环境中的 HTTP 代理配置；代理凭据和代理可见流量不属于 v1 审查范围。插件审查会披露本地主机用户权限、结构化 argv、环境来源、端点、认证来源名称、作用域和工具过滤器，但不会读取或打印机密值。 |
| 38 | |
| 39 | 信任（Trust）会暂存已审查的内容，但不会启用它。启用操作会把该暂存快照附加到当前工作区的 MCP 池。禁用、撤销以及其他跨进程的代际变更会移除目录条目、取消进行中的操作，并终止插件的 stdio 子进程。在每次分派/目录边界之前，源码或暂存树的漂移都会被完全重新验证，并让下一个边界失败关闭；v0.9.1 不会在已经运行的调用期间持续对可变树做哈希，因此不承诺由漂移触发的调用中途取消。MCP 订阅不会通过插件包暴露。完整的生命周期契约请参阅[插件包](../PLUGIN_BUNDLES.md)。 |
| 40 | |
| 41 | ## MCP 配置引导 |
| 42 | |
| 43 | 在解析出的 MCP 路径处创建一份入门 MCP 配置： |
| 44 | |
| 45 | ```bash |
| 46 | codewhale-tui mcp init |
| 47 | ``` |
| 48 | |
| 49 | `codewhale-tui setup --mcp` 会在技能设置的同时执行相同的 MCP 引导。 |
| 50 | |
| 51 | 常用管理命令： |
| 52 | |
| 53 | ```bash |
| 54 | codewhale-tui mcp list |
| 55 | codewhale-tui mcp tools [server] |
| 56 | codewhale-tui mcp add <name> --command "<cmd>" --arg "<arg>" |
| 57 | codewhale-tui mcp add <name> --url "http://localhost:3000/mcp" |
| 58 | codewhale-tui mcp add <name> --url "https://example.com/mcp" --bearer-token-env-var MCP_TOKEN |
| 59 | codewhale-tui mcp login <name> |
| 60 | codewhale-tui mcp logout <name> |
| 61 | codewhale-tui mcp enable <name> |
| 62 | codewhale-tui mcp disable <name> |
| 63 | codewhale-tui mcp remove <name> |
| 64 | codewhale-tui mcp validate |
| 65 | ``` |
| 66 | |
| 67 | ## TUI 内管理器 |
| 68 | |
| 69 | 在交互式 TUI 中，`/mcp` 会为解析出的 MCP 配置路径打开一个紧凑的管理器。它显示每个已配置的服务器、该服务器是启用还是禁用、其传输方式、命令或 URL、超时值、连接错误，以及运行发现后得到的工具/资源/提示。 |
| 70 | |
| 71 | TUI 内支持的操作： |
| 72 | |
| 73 | ```text |
| 74 | /mcp init |
| 75 | /mcp init --force |
| 76 | /mcp import |
| 77 | /mcp recommendations |
| 78 | /mcp add recommended <id> |
| 79 | /mcp add stdio <name> <command> [args...] |
| 80 | /mcp add http <name> <url> |
| 81 | /mcp login <name> [--scope scope] |
| 82 | /mcp logout <name> |
| 83 | /mcp enable <name> |
| 84 | /mcp disable <name> |
| 85 | /mcp remove <name> |
| 86 | /mcp validate |
| 87 | /mcp reload |
| 88 | ``` |
| 89 | |
| 90 | ### 推荐插件与配套集成 |
| 91 | |
| 92 | `/mcp recommendations` 是 Codewhale 原生的精选建议界面。条目被描述为产品插件，带有其组件类型和来源，但 `/mcp add recommended <id>` 仍然只写入指定的 MCP 服务器组件。查看推荐绝不会获取、安装、信任或启用任何内容。添加一条推荐会写入配置；服务器只有在显式执行 `/mcp restart` 之后才会首次启动。 |
| 93 | |
| 94 | v0.9.10 的产品建议使用这些经过审查的固定版本定义。Plugins 视图是产品/安装界面；MCP、Skills 和沙箱适配器是透明的组件类型，它们各自的标签页仍然是可操作和可诊断的界面： |
| 95 | |
| 96 | | 插件 | 组件 | 固定版本定义 | 来源与成熟度 | 安装边界 | |
| 97 | | --- | --- | --- | --- | --- | |
| 98 | | Chrome DevTools | MCP 服务器（stdio） | `npx -y chrome-devtools-mcp@1.7.0`（Windows 上为 `npx.cmd`） | [ChromeDevTools 官方项目](https://github.com/ChromeDevTools/chrome-devtools-mcp) | 用户重启 MCP 时，npm 可能会下载固定版本的包。 | |
| 99 | | Playwright | MCP 服务器（stdio） | `npx -y @playwright/mcp@0.0.79 --isolated`（Windows 上为 `npx.cmd`） | [微软官方项目](https://github.com/microsoft/playwright-mcp) | `--isolated` 会启动全新的浏览器配置文件；npm 只会在显式重启后才下载固定版本的包。 | |
| 100 | | Computer Use | 第一方插件（MCP + skill） | 随二进制内置为 `computer-use` 插件 | Codewhale；通过 `/plugin` 或扩展市场启用 | 这是 Codewhale 唯一推荐的计算机操作集成。此处不再列出第三方桌面控制 MCP。 | |
| 101 | | Browser Use | Skill 加单独安装的 Python 运行时 | Skill/运行时版本 `0.13.8` | [browser-use 官方项目](https://github.com/browser-use/browser-use) | 可选配套：不是 MCP 服务器。Codewhale 不会自动运行上游的 Skill 安装器，也不会安装其浏览器/运行时依赖。 | |
| 102 | | Anthropic Sandbox Runtime | 沙箱适配器配套 | `@anthropic-ai/sandbox-runtime@0.0.73` | [anthropic-experimental 官方项目](https://github.com/anthropic-experimental/sandbox-runtime)；测试版 | v0.9.10 中仅文档说明的适配器候选：不是 MCP 服务器，也不是活跃的 Codewhale 插件适配器。它不会取代 Codewhale 的沙箱策略。 | |
| 103 | |
| 104 | [Container Use](https://github.com/dagger/container-use) 仍然是一个带有 MCP 服务器组件（`container-use stdio`）的额外实验性建议。该二进制必须单独安装；`/mcp add recommended container-use` 只写入配置，Codewhale 绝不会下载它。 |
| 105 | |
| 106 | 这种呈现方式遵循了本地 Grokbuild 扩展视图中的同样有用的边界（一个产品插件可以暴露 MCP 或 Skill 组件，同时组件标签页仍可检查）、Kimi 市场的显式显示名称/层级/来源字段，以及 Codex 市场的显式来源和安装策略字段。Codewhale 保持其更严格的规则：来源和外部策略只是显示元数据，绝不会被继承为信任或自动安装。完整的插件包和市场语义请参阅[插件包](../PLUGIN_BUNDLES.md)。 |
| 107 | |
| 108 | `/mcp validate`（别名 `/mcp doctor`）只为了 UI 发现而重新连接：它刷新你在分页器中看到的管理器快照，而不是模型拿到的目录。 |
| 109 | |
| 110 | `/mcp reload`（别名 `/mcp reconnect`、`/mcp restart`）是热重载路径。它会重新读取 MCP 配置来源，并通过引擎持有的连接池重新连接，因此重建后的目录正是下一个模型回合所用的目录——无需重启 TUI。从 TUI 中做出的配置修改会立即写入，管理器会把快照标记为需要重载，直到你运行它；重载失败会保留之前活跃的连接池不变，并如实说明。 |
| 111 | |
| 112 | 无头界面是例外：`ConfigReload` 应用服务器请求**不会**刷新 MCP 连接，因此无头运行时在 MCP 配置变更后仍然需要重启。 |
| 113 | |
| 114 | ## 远程 HTTP 认证 |
| 115 | |
| 116 | 基于 URL 的 MCP 服务器可以使用静态请求头、环境变量派生的请求头、bearer-token 环境变量或 OAuth。授权优先级是保守的： |
| 117 | |
| 118 | 1. `headers` 和 `env_headers` 首先应用。 |
| 119 | 2. 若 `Authorization` 头尚未设置，`bearer_token_env_var` 会添加 `Authorization: Bearer <env value>`。 |
| 120 | 3. 仅当不存在 `Authorization` 头时，才使用存储的 OAuth 凭据。 |
| 121 | |
| 122 | 对于 bearer-token 认证，推荐使用环境变量支持的配置： |
| 123 | |
| 124 | ```json |
| 125 | { |
| 126 | "servers": { |
| 127 | "remote": { |
| 128 | "url": "https://example.com/mcp", |
| 129 | "bearer_token_env_var": "EXAMPLE_MCP_TOKEN" |
| 130 | } |
| 131 | } |
| 132 | } |
| 133 | ``` |
| 134 | |
| 135 | 对于通用的远程 MCP OAuth，添加 URL 服务器并运行登录： |
| 136 | |
| 137 | ```bash |
| 138 | codewhale-tui mcp add remote --url "https://example.com/mcp" |
| 139 | codewhale-tui mcp login remote |
| 140 | ``` |
| 141 | |
| 142 | Codewhale 会发现服务器的 OAuth 元数据，在你的浏览器中打开授权 URL，监听本地回调，交换授权码，并通过 Codewhale 的机密后端存储令牌响应。存储的 OAuth 令牌会按服务器名称加 URL 查找，并在可能的情况下于请求前刷新。登录期间，CLI 会打印授权 URL 和等待状态，同时本地回调监听器处于活动状态。如果基于 URL 的服务器在连接/发现期间返回 401 或 Unauthorized，`codewhale mcp connect <name>` 会报告需要 OAuth 认证，并指向 `codewhale mcp login <name>`。资源辅助工具的列表还会为认证类失败显示 `authentication_required` 条目，而不是静默地看起来为空。 |
| 143 | |
| 144 | 可选的 OAuth 字段： |
| 145 | |
| 146 | ```json |
| 147 | { |
| 148 | "servers": { |
| 149 | "remote": { |
| 150 | "url": "https://example.com/mcp", |
| 151 | "scopes": ["tools/read"], |
| 152 | "oauth": { |
| 153 | "client_id": "public-client-id" |
| 154 | }, |
| 155 | "oauth_resource": "https://example.com" |
| 156 | } |
| 157 | } |
| 158 | } |
| 159 | ``` |
| 160 | |
| 161 | 当提供方要求固定重定向时，用户级配置可以设置回调行为： |
| 162 | |
| 163 | ```toml |
| 164 | mcp_oauth_callback_port = 1455 |
| 165 | mcp_oauth_callback_url = "http://127.0.0.1:1455/callback" |
| 166 | ``` |
| 167 | |
| 168 | 这些回调字段会在项目作用域的配置覆盖中被忽略。 |
| 169 | |
| 170 | ## Hugging Face MCP |
| 171 | |
| 172 | Hugging Face 为 Hub 资源、文档、数据集、Spaces 和社区工具提供了一个托管的 MCP 服务器。Codewhale 不会从 `/hf` 调用 Hugging Face 的 Hub HTTP API；它只帮助你检查并设置常规 MCP 管理器将要加载的 MCP 配置。 |
| 173 | |
| 174 | 推荐的设置路径是 Hugging Face 的设置页生成的配置： |
| 175 | |
| 176 | 1. 登录后访问 <https://huggingface.co/settings/mcp>。 |
| 177 | 2. 选择最接近你的 Codewhale 配置形态的 MCP 客户端，并复制生成的服务器片段。 |
| 178 | 3. 将 Hugging Face 服务器条目粘贴到解析出的 MCP 配置文件中。 |
| 179 | 4. 运行 `/mcp reload` 重建模型可见的实时工具池。 |
| 180 | |
| 181 | Codewhale 同时读取 `servers` 和 `mcpServers`，因此设置页生成的片段可以在不更改 MCP 文件其余部分的情况下适配。纯占位符的形态如下所示： |
| 182 | |
| 183 | ```json |
| 184 | { |
| 185 | "servers": { |
| 186 | "huggingface": { |
| 187 | "url": "https://huggingface.co/mcp", |
| 188 | "headers": { |
| 189 | "Authorization": "Bearer ${HF_TOKEN}" |
| 190 | } |
| 191 | } |
| 192 | } |
| 193 | } |
| 194 | ``` |
| 195 | |
| 196 | 上面的占位符不是可运行的机密。请在私有 MCP 配置中使用设置页生成的值，并且永远不要提交真实的 Hugging Face 令牌。 |
| 197 | |
| 198 | 交互式辅助命令： |
| 199 | |
| 200 | ```text |
| 201 | /hf mcp status |
| 202 | /hf mcp setup |
| 203 | /hf concepts |
| 204 | ``` |
| 205 | |
| 206 | `/hf mcp status` 会检查已配置的 MCP 文件，查找常见的 Hugging Face 服务器名称或 Hugging Face MCP URL。`/hf concepts` 解释 Hugging Face provider 路由、Hugging Face MCP 和显式 Hub 工作流之间的区别。 |
| 207 | |
| 208 | 官方文档：<https://huggingface.co/docs/hub/hf-mcp-server> |
| 209 | |
| 210 | ## 配置文件位置 |
| 211 | |
| 212 | 默认路径： |
| 213 | |
| 214 | - `~/.codewhale/mcp.json`（当 Codewhale 文件不存在时，仍会读取 `~/.deepseek/mcp.json`） |
| 215 | |
| 216 | 覆盖方式： |
| 217 | |
| 218 | - 配置项：`mcp_config_path = "/path/to/mcp.json"` |
| 219 | - 环境变量：`DEEPSEEK_MCP_CONFIG=/path/to/mcp.json` |
| 220 | |
| 221 | `codewhale-tui mcp init`（以及 `codewhale-tui setup --mcp`）会写入这个解析出的路径。 |
| 222 | |
| 223 | 交互式 `/config` 编辑器也会暴露 `mcp_config_path`。在 TUI 中更改它，会更新 `/mcp` 使用的路径，并将连接池标记为需要重载；随后 `/mcp reload` 会把实时连接池切换到新的配置来源。 |
| 224 | |
| 225 | 编辑 MCP 文件或更改 `mcp_config_path` 后，运行 `/mcp reload`。无需重启 TUI。 |
| 226 | |
| 227 | ## 工具命名 |
| 228 | |
| 229 | 发现的 MCP 工具会以如下形式暴露给模型： |
| 230 | |
| 231 | - `mcp_<server>_<tool>` |
| 232 | |
| 233 | 例如：名为 `git` 的服务器上的名为 `status` 的工具会变成 `mcp_git_status`。 |
| 234 | |
| 235 | 命令面板包含按服务器分组的 MCP 条目。它会显示已禁用和失败的服务器，而不是隐藏它们，并使用与展示给模型的相同的运行时工具名。 |
| 236 | |
| 237 | ## 资源与提示辅助工具 |
| 238 | |
| 239 | 启用 MCP 时，CLI 还会暴露辅助工具： |
| 240 | |
| 241 | - `list_mcp_resources`（可选 `server` 过滤器） |
| 242 | - `list_mcp_resource_templates`（可选 `server` 过滤器） |
| 243 | - `mcp_read_resource` / `read_mcp_resource`（别名） |
| 244 | - `mcp_get_prompt` |
| 245 | |
| 246 | ## 最小示例 |
| 247 | |
| 248 | ```json |
| 249 | { |
| 250 | "timeouts": { |
| 251 | "connect_timeout": 10, |
| 252 | "execute_timeout": 60, |
| 253 | "read_timeout": 120 |
| 254 | }, |
| 255 | "servers": { |
| 256 | "example": { |
| 257 | "command": "node", |
| 258 | "args": ["./path/to/your-mcp-server.js"], |
| 259 | "env": {}, |
| 260 | "disabled": false |
| 261 | } |
| 262 | } |
| 263 | } |
| 264 | ``` |
| 265 | |
| 266 | 为了与其他客户端兼容，你也可以使用 `mcpServers` 而不是 `servers`。 |
| 267 | |
| 268 | ## 将 Codewhale 作为 MCP 服务器运行 |
| 269 | |
| 270 | 你可以把本地 Codewhale 二进制注册为 MCP 服务器，这样其他 Codewhale 会话（或任何 MCP 客户端）就能调用它的工具。 |
| 271 | |
| 272 | ### 快速设置 |
| 273 | |
| 274 | ```bash |
| 275 | codewhale-tui mcp add-self |
| 276 | ``` |
| 277 | |
| 278 | 这会解析当前二进制路径，生成一个运行 `codewhale-tui serve --mcp` 的配置条目，并将其写入你的 MCP 配置文件。默认服务器名称是 `codewhale`。 |
| 279 | |
| 280 | 选项： |
| 281 | |
| 282 | - `--name <NAME>` — 自定义服务器名称（默认：`codewhale`） |
| 283 | - `--workspace <PATH>` — 服务器的工作目录 |
| 284 | |
| 285 | ### 手动配置 |
| 286 | |
| 287 | `~/.codewhale/mcp.json` 中等价的手动条目： |
| 288 | |
| 289 | ```json |
| 290 | { |
| 291 | "servers": { |
| 292 | "codewhale": { |
| 293 | "command": "/path/to/codewhale", |
| 294 | "args": ["serve", "--mcp"], |
| 295 | "env": {} |
| 296 | } |
| 297 | } |
| 298 | } |
| 299 | ``` |
| 300 | |
| 301 | `codewhale-tui` 二进制直接支持 `serve --mcp`。`codewhale` 调度器提供等价的 `codewhale mcp-server` stdio 入口点。使用你 `PATH` 中的那一个（运行 `which codewhale` 或 `which codewhale-tui` 找到完整路径）。`mcp add-self` 命令会自动解析出正确的二进制。 |
| 302 | |
| 303 | ### 前提条件 |
| 304 | |
| 305 | - `command` 引用的二进制必须存在且可执行。 |
| 306 | - MCP 服务器通过 stdio 作为子进程运行——不需要网络端口。 |
| 307 | - 每个 MCP 客户端会话都会生成自己的服务器进程。 |
| 308 | |
| 309 | ### 工具命名 |
| 310 | |
| 311 | 来自 MCP 服务器的工具遵循标准命名约定： |
| 312 | |
| 313 | - `mcp_<server>_<tool>` |
| 314 | |
| 315 | 例如，来自默认服务器（名为 `codewhale`）的 `shell` 工具会变成 `mcp_codewhale_shell`。 |
| 316 | |
| 317 | ### MCP 服务器 vs HTTP/SSE API vs ACP |
| 318 | |
| 319 | | | `codewhale-tui serve --mcp` | `codewhale-tui serve --http` | `codewhale-tui serve --acp` | |
| 320 | |---|---|---|---| |
| 321 | | **协议** | MCP stdio | HTTP/SSE JSON-RPC | ACP stdio | |
| 322 | | **用例** | 面向 MCP 客户端的工具服务器 | 面向应用的运行时 API | 面向 Zed/自定义 ACP 客户端的编辑器代理 | |
| 323 | | **配置** | `~/.codewhale/mcp.json` 条目 | 直接 URL 连接 | 编辑器的 `agent_servers` 自定义命令 | |
| 324 | | **生命周期** | 按客户端会话生成 | 长时间运行的守护进程 | 按编辑器代理会话生成 | |
| 325 | |
| 326 | 当你希望 Codewhale 工具对其他 MCP 客户端可用时，使用 `mcp add-self`。在构建直接消费 API 的应用时，使用 `serve --http`。当编辑器想以 ACP 代理身份与 Codewhale 对话时，使用 `serve --acp`。 |
| 327 | |
| 328 | ### 验证 |
| 329 | |
| 330 | 添加之后，测试连接： |
| 331 | |
| 332 | ```bash |
| 333 | codewhale-tui mcp validate |
| 334 | codewhale-tui mcp tools codewhale |
| 335 | ``` |
| 336 | |
| 337 | ## 服务器字段 |
| 338 | |
| 339 | 每个服务器的设置： |
| 340 | |
| 341 | - `command`（字符串，必需） |
| 342 | - `args`（字符串数组，可选） |
| 343 | - `env`（对象，可选） |
| 344 | - `connect_timeout`、`execute_timeout`、`read_timeout`（秒，可选） |
| 345 | - `disabled`（布尔值，可选） |
| 346 | - `enabled`（布尔值，可选，默认 `true`） |
| 347 | - `required`（布尔值，可选）：如果该服务器无法初始化，启动/连接验证会失败。 |
| 348 | - `enabled_tools`（数组，可选）：该服务器的工具名称允许列表。 |
| 349 | - `disabled_tools`（数组，可选）：在 `enabled_tools` 之后应用的拒绝列表。 |
| 350 | - `url`（字符串，可选）：远程 MCP 服务器的 Streamable HTTP 端点。 |
| 351 | - `transport`（字符串，可选）：对于传统 SSE 端点，设为 `"sse"`。 |
| 352 | - `headers`（对象，可选）：基于 URL 的服务器使用的字面量 HTTP 请求头。 |
| 353 | - `env_headers` 或 `env_http_headers`（对象，可选）：请求头名称到环境变量名称的映射。 |
| 354 | - `bearer_token_env_var`（字符串，可选）：包含 bearer token 的环境变量。 |
| 355 | - `scopes`（数组，可选）：`mcp login` 的默认 OAuth 作用域。 |
| 356 | - `oauth.client_id`（字符串，可选）：预先注册的 OAuth 客户端 ID。 |
| 357 | - `oauth_resource`（字符串，可选）：附加到授权 URL 的资源参数。 |
| 358 | |
| 359 | ## 安全说明 |
| 360 | |
| 361 | MCP 工具与内置工具走相同的审批框架。只读的 MCP 辅助工具（资源/提示的列出与读取）在策略允许时，可以在 Ask 和 Auto-Review 中无提示地运行，而会产生副作用的 MCP 工具则需要审批。Full Access 不会绕过强制性的策略拦截。 |
| 362 | |
| 363 | 你仍然应该只配置你信任的 MCP 服务器，并把 MCP 服务器配置视为与在你的机器上运行代码等价。避免提交字面量的 `Authorization` 请求头。优先使用 `env_headers`、`bearer_token_env_var` 或 OAuth 登录，让机密保持在 MCP 文件之外。 |
| 364 | |
| 365 | ## 故障排查 |
| 366 | |
| 367 | - 运行 `codewhale-tui doctor` 确认它解析出的 MCP 配置路径以及该路径是否存在。 |
| 368 | - 在 TUI 中运行 `/mcp validate` 刷新可见的服务器/工具快照。 |
| 369 | - 如果配置或凭据变更后模型的目录中缺少工具，运行 `/mcp reload` —— `/mcp validate` 只刷新 UI 快照。 |
| 370 | - 如果 MCP 配置缺失，运行 `codewhale-tui mcp init --force` 重新生成它。 |
| 371 | - 如果工具没有出现，请验证服务器命令能否在你的 shell 中工作，以及服务器是否支持 MCP 的 `tools/list`。 |
| 372 |