MCP 服务器

MCP 服务器允许智能体调用外部工具，例如浏览器自动化、文档检索、GitHub API 以及各类内部系统。

这是 Kaiwu 作为消费端使用 MCP 的场景。若希望通过编辑器或自动化脚本来反向驱动 Kaiwu 本身，请参阅另一方向的文档： Kaiwu MCP（外部）。

Kaiwu 提供了统一的管理入口，可在桌面应用、守护进程与 CLI 之间集中管理这些服务：

• 在 Kaiwu 中一次定义，多处复用
• 自定义各服务器的默认生效范围
• 导入现有的宿主 MCP JSON 配置
• 自动检测 Claude、Codex 或 OpenCode 中已配置的 MCP 服务器
• 针对特定后端、设备与工作区，实时预览确切生效的工具集
• 针对单次会话临时覆盖 Kaiwu 托管的 MCP 选择，且不改动已保存的默认配置

MCP 服务器与 Kaiwu 工具

MCP 服务器是更宏大的 Kaiwu 工具体系中的一部分。

这意味着：

• Kaiwu 内置操作与自定义 MCP 工具将被统一配置，并作为整体工具面交付给模型
• 支持原生 MCP 的提供商可直接通过 MCP 协议接收工具
• 使用 Kaiwu shell bridge 的提供商则通过 CLI 桥接方式，同样能获取这些由 Kaiwu 托管的工具

因此，即便当前所选的提供商不提供原生 MCP 清单接口，本页面依然是配置自定义 MCP 工具的正确入口。

如需了解完整的产品模型，请参阅 Kaiwu 工具与操作。

在何处管理 MCP 服务器

在桌面应用中：

• Settings → MCP servers（设置 → MCP 服务器）

在 CLI 中，常用命令示例如下：

kaiwu mcp servers list
kaiwu mcp servers test --mcp-server <name-or-id>
kaiwu mcp servers detect --provider codex

运行 kaiwu mcp servers --help 可查看当前的子命令与参数列表。

桌面端 UI、守护进程与 CLI 均使用同一套基于账号同步的 MCP 配置。

Kaiwu MCP（外部控制面）

除了管理其他 MCP 服务器外，Kaiwu 自身也能作为 MCP 服务器运行，以便外部 MCP 客户端控制会话并执行 Kaiwu 操作：

kaiwu mcp serve

指南：Kaiwu MCP（外部）

MCP 设置界面布局

MCP 设置界面包含三个标签页：

已配置（Configured）

展示直接在 Kaiwu 中管理的 MCP 服务器。

在该标签页中，你可以：

• 查看已保存的服务器
• 编辑或删除服务器
• 添加新服务器
• 快速安装常用预设

已检测（Detected）

展示 Kaiwu 在所选设备的原生配置文件中发现的 MCP 服务器。

目前，Kaiwu 支持自动检测以下提供商的原生 MCP 服务器：

• Claude
• Codex
• OpenCode

已检测到的服务器显示为只读。你可以借助该视图了解所选后端当前已有的配置，也可将这些定义导入到 Kaiwu 托管的 MCP 设置中。

预览（Preview）

展示在以下特定组合下实际生效的工具视图：

• 后端 / 提供商
• 设备
• 工作区或目录

当你想明确以下问题时，请使用该标签页：

• “当前会话实际能看到哪些工具？”
• “此处默认生效哪些 Kaiwu 托管的服务器？”
• “该后端已有现存的哪些提供商原生 MCP 服务器？”
• “哪些已保存的服务器处于可用状态，但当前尚未应用？”

添加服务器

在 Kaiwu 中添加新的 MCP 服务器时，可通过以下三种方式进入：

手动配置（Configure）

适用于需要手动定义服务器的场景。

Kaiwu 支持：

• 本地命令（Local command） (stdio)
• 远程 HTTP（Remote HTTP）
• 远程 SSE（Remote SSE）

对于本地命令型服务器，核心字段为命令行，你可以直接粘贴各类 README 中的常见命令。Kaiwu 会在内部自动将其拆解为命令与参数。

对于远程服务器，你需要提供：

• URL
• 可选的请求头（headers）
• 可选的环境变量

导入 JSON（Import JSON）

适用于项目 README 或其他工具已提供宿主 MCP JSON 片段的场景。

Kaiwu 支持常见的宿主 MCP JSON 格式，例如：

• mcpServers
• servers
• 嵌套的 mcp.servers

当项目要求粘贴类似以下内容时，“导入 JSON”会非常方便：

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

Kaiwu 会解析支持的字段并供你复核，随后将其转换为常规的 Kaiwu 托管 MCP 条目。

快速安装（Quick install）

适用于快速搭建常用的开发者 MCP 服务器。

目前精选的预设包括：

• Playwright
• Context7
• Sequential Thinking
• GitHub

部分预设可立即完成安装；另一些预设则可能需要配置后续认证映射，例如关联已保存的密钥（Saved Secret）或设备环境变量。

“生效范围”（Applies to）详解

每个由 Kaiwu 托管的 MCP 服务器都在 Applies to 项下定义了默认作用域规则。

该规则决定了 Kaiwu 在何处自动引入该服务器。

支持的作用域包括：

• 所有设备（All machines）——适用于可移植的服务器，尤其是远程 HTTP/SSE 服务器
• 单个设备（One machine）——适用于安装在特定设备上的本地命令型服务器
• 单设备单工作区（One workspace on one machine）——适用于仅应在特定项目目录下生效的服务器

示例：

• 远程 GitHub MCP 服务器通常适用于所有设备
• 本地 npx @playwright/mcp 配置通常归属于单个设备
• 基于仓库文件启动的特定项目 MCP 服务器，通常应设为单设备单工作区

注意事项：

• 这些规则仅为默认生效规则，并非后续所有会话不可逾越的硬性限制
• 在新建会话时，你仍可通过 MCP 标签临时覆盖 Kaiwu 托管的服务器选择

密钥、认证与环境变量

Kaiwu 支持通过以下方式配置 MCP 的环境变量与请求头：

• 已保存的密钥（Saved Secrets）——推荐
• 设备环境引用（machine environment references），例如 ${MY_TOKEN}
• **明文（plain text）**值

推荐用法：

• 对于可复用的 Token 与 API Key，建议使用 Saved Secrets
• 若配置值需取自目标设备上的守护进程或 shell 环境，使用设备环境引用
• 除非是非敏感数据，否则尽量避免使用明文

Saved Secrets 对需要认证头的远程 MCP 服务器尤为实用，例如：

• Authorization: Bearer ...
• GitHub Token
• 私有 API Token

测试 MCP 服务器

在 MCP 设置流程中，可以直接测试每个由 Kaiwu 托管的 MCP 服务器。

测试会验证 Kaiwu 是否能够：

• 解析配置
• 解析已保存的密钥及环境引用
• 成功启动或连接至服务器
• 正常获取工具列表

这是排查以下问题的最快途径：

• 命令行配置错误
• 本地依赖未安装
• URL 错误
• 缺少认证凭据
• 缺少设备环境变量

已检测到的提供商原生 MCP 服务器

**已检测（Detected）**标签页会显示所选提供商自身配置文件中已配好的 MCP 服务器。

这在以下场景中非常有用：

• 在使用 Kaiwu 之前，已在 Claude、Codex 或 OpenCode 中配置了 MCP
• 需要对比提供商原生配置与 Kaiwu 托管的默认配置
• 希望将现有的提供商原生服务器导入至 Kaiwu

注意事项：

• 检测到的条目仅供参考且为只读
• 列表会针对所选的设备与目录动态刷新
• 提供商原生 MCP 与 Kaiwu 托管 MCP 均会影响最终会话的工具可用情况

启动会话前预览

**预览（Preview）**标签页可展示在特定上下文中会话将实际使用的工具。

它整合了以下内容：

• Kaiwu 内置工具面
• 默认生效的 Kaiwu 托管 MCP 服务器
• 针对所选后端及上下文检测到的提供商原生 MCP 服务器
• 可用但当前未应用的 Kaiwu 托管服务器

在开启重要会话前（尤其是跨多台设备或多个工作区时），使用“预览”功能可确保配置符合预期。

新建会话编辑区中的 MCP

启动新会话时，编辑区会显示一个 MCP 标签，例如：

• MCP (3)

其中的数字表示当前会话上下文中包含的 MCP 数量。

点击该标签即可打开 MCP 选择器。

在该界面中，你可以：

• 查看默认选中的 Kaiwu 托管服务器
• 仅为本次会话添加额外的 Kaiwu 托管服务器
• 排除通常默认生效的 Kaiwu 托管服务器
• 查看所选后端已配置的提供商原生检测服务器

重要限制：

• 提供商原生检测条目仅作为只读上下文展示
• Kaiwu 内置工具面始终处于启用状态
• 选择器中的调整仅对即将启动的本次会话生效，不会覆盖已保存的账号默认配置

修改 MCP 设置后的生效机制

MCP 设置将在下次会话启动时生效。

这意味着：

• 修改 MCP 服务器只会影响后续的新会话
• 不会对正在运行中的会话进行工具热替换
• 恢复已暂停的会话时，将继续沿用该会话启动时的会话级工具状态

支持的提供商与重要特性

工具的具体投递机制取决于所选的后端。

目前 Kaiwu 主要通过两条途径投递托管的 MCP 工具：

• 原生 MCP 投递：适用于支持原生 MCP 的后端，包括 Claude、Codex、OpenCode 以及兼容的自定义 ACP 后端
• Shell 桥接投递：适用于使用 Kaiwu 工具桥接的后端

重要区别：

• 仅当提供商本身具备原生 MCP 配置模型时，才能检测到提供商原生 MCP 配置
• 对于不支持原生 MCP 投递的提供商，Kaiwu 托管的自定义 MCP 工具仍可通过 shell 桥接完成投递

各提供商的支持情况可能会随版本迭代而变化，请以各提供商文档及特性矩阵为准。

另请参阅：

• Claude
• Codex
• OpenCode
• Kaiwu 工具与操作

严格模式（Strict mode）

严格模式决定了 Kaiwu 在遇到无效 MCP 配置时的处理方式。

• 关闭（Off）：Kaiwu 会尽可能跳过无效的 MCP 条目，并继续启动会话
• 开启（On）：若任何已启用且生效的 MCP 服务器无法正常解析，Kaiwu 将直接终止会话启动

若希望启动行为遵循“遇错即停（fail-closed）”而非“尽力而为（best-effort）”，请开启严格模式。

常见用例

在单台设备上全局使用 Playwright

1. 打开 Settings → MCP servers
2. 从 Quick install 中添加 Playwright
3. 将 Applies to 设置为 One machine
4. 进行连接测试
5. 在该设备上启动会话，确认 MCP 标签中已包含该服务

在所有设备上复用远程 GitHub MCP 服务器

1. 选择 Remote HTTP 添加服务器
2. 将 Token 保存为 Saved Secret
3. 将 Applies to 设置为 All machines
4. 在即将运行会话的设备上进行连接测试

直接导入 README 中的配置片段，无需手动新建

1. 从 README 中复制宿主 MCP JSON 代码
2. 打开 Add server → Import JSON
3. 粘贴 JSON 内容
4. 核对解析结果
5. 将敏感信息映射为 Saved Secret 或设备环境引用
6. 保存并测试

为单次会话临时调整 MCP 选择

1. 打开新建会话界面
2. 点击 MCP 标签
3. 取消勾选本次不需要的默认 Kaiwu 托管服务器
4. 勾选仅在本次会话中额外启用的 Kaiwu 托管服务器
5. 启动会话

故障排查

“服务器已保存，但未出现在我的会话中”

请检查以下各项：

• 当前选中的设备
• 当前选中的工作区或目录
• 该服务器的 Applies to 生效规则
• 所选后端的工具投递支持情况
• 新建会话界面中的 MCP 标签（此处的会话级设置可能覆盖了 Kaiwu 托管的默认规则）

此外，可在启动会话前借助**预览（Preview）**标签页确认最终的实际生效结果。

“已检测（Detected）中显示的内容与预期不符”

请检查以下各项：

• 当前选中的设备
• 当前选中的目录或工作区
• 该后端是将 MCP 配置存储在用户级文件、项目级文件，还是两者兼有

“已检测”标签页与上下文强相关，会根据当前选中的设备与目录动态刷新。

“测试失败”

最常见的原因包括：

• 对应设备上未安装该本地命令
• URL 填写错误
• 缺少必需的 Token 或请求头
• 运行守护进程的主机上不存在所引用的设备环境变量

“修改了 MCP 设置，但当前会话没有任何变化”

这符合预期设计。

MCP 设置仅在下次会话启动时生效。请新建一个会话以加载更新后的配置。

相关页面

• Kaiwu 工具与操作
• 已连接服务
• Profiles
• 提供商集成
• Claude
• Codex
• OpenCode