a4agent 自 0.2.2 起内置 MCP server 管理,经四端、六端、七端(0.6.1 新增 OpenCode)、八端(0.6.3 新增 WorkBuddy)演进到九端(0.7.2 新增 TRAE):把九端各自配置里的 MCP server 归一为统一视图(name / transport / command / args / env / url / headers),自动发现并聚合标注,支持从零安装与 JSON 批量导入(自 0.2.3 起)、跨端迁移(按传输能力矩阵严格校验)、快照回收站与迁移日志。其中 TRAE 端为只读发现——它的 MCP 配置存于加密内部库,安装 / 迁移请在 TRAE 界面操作。密钥全程脱敏或用 DPAPI 加密,API 永不回传明文。本文章介绍 MCP 的发现与聚合、安装方式、功能介绍、配置文件位置、传输能力矩阵、跨端迁移与回收站机制。

1. 功能概述

维度 说明
管理对象 九端配置中的 MCP server(stdio / sse / http / streamable-http 传输)
统一视图 { name, transport, command, args, env, url, headers, cwd } 归一 schema
适用端 Claude Code、Codex、dsh、ZCode(0.2.2 起)、pi 与 Qoder(0.5.0 起)、OpenCode(0.6.1 起)、WorkBuddy(0.6.3 起,仅全局)、TRAE(0.7.2 起,只读发现)
核心能力 发现聚合、从零安装与 JSON 批量导入(0.2.3 起)、跨端迁移、快照回收站、迁移日志、功能介绍
安全特性 env / headers 一律脱敏;回收站快照 DPAPI 加密

1.1 与技能管理的差异

MCP 与 技能管理 管理骨架同构,但配置形态不同:skill 是独立目录,MCP server 是配置文件内的嵌套子结构,因此读写走各端的配置文件适配器,迁移语义为「配置片段复制」,冲突处理为「目标端同名先快照进回收站再写入」。

2. 配置文件位置

端 全局(用户级) 项目级 server 存放位置
Claude Code ~/.claude.json 顶层 mcpServers <项目>/.mcp.json mcpServers 对象
Codex ~/.codex/config.toml <项目>/.codex/config.toml [mcp_servers.*] 子表
dsh ~/.dsh/profiles/<profile>/cordis.patch.yml 不支持(cordis 为全局 profile 层) @deepseek-ai/dsh-mcp-client 插件的 insert 条目
ZCode ~/.zcode/cli/config.json <项目>/.zcode/config.json 嵌套 mcp.servers(严格 schema 只写规范键)
pi ~/.pi/agent/mcp.json <项目>/.pi/mcp.json(需该项目被 pi 信任) 顶层 mcpServers(与 Claude Code 同构)
Qoder ~/.qoder/mcp.json 不托管(与 Claude Code 共用 <项目>/.mcp.json,归 claude 端) 顶层 mcpServers
OpenCode ~/.config/opencode/opencode.json(c) <项目>/.opencode/opencode.json(c)(优先于项目根同名文件) 嵌套 mcp.servers
WorkBuddy ~/.workbuddy/mcp.json(可用 A4AGENT_WORKBUDDY_MCP_PATH 覆盖) 不支持(仅全局) 顶层 mcpServers(与 Claude Code 同构)
TRAE ~/.trae-cn/mcps/<工作区>/<agent>/(运行时明文缓存,只读;真正配置在加密内部库) 不支持 缓存目录内 SERVER_METADATA.json + tools/*.json

路径全部可通过环境变量覆盖(详见数据目录与日志说明);dsh 的 profile 默认 web,可用 A4AGENT_DSH_MCP_PROFILE 指定;Qoder 的配置目录名随发行版而变(国际版 .qoder、国内版 .qoder-cn),可用 A4AGENT_QODER_HOME 指定;TRAE 的缓存路径可用 A4AGENT_TRAE_MCP_CACHE_PATH 覆盖。

TRAE 端为什么只读:TRAE 的用户级 MCP 配置保存在加密内部库(ModularData 下的非标准 SQLite 数据库),明文侧只有运行时缓存 ~/.trae-cn/mcps/<工作区>/<agent>/,缓存里没有连接参数(命令 / 密钥等)。因此 a4agent 对 TRAE 只做只读发现——读缓存把「TRAE 里有哪些 server」如实列出来;写入 / 删除 / 迁移闸门全部拒绝并如实标注只读,安装与迁移请在 TRAE 界面操作。

Qoder 端视图常常「一个 server 都没有」是正常的:会话里实际连接的 MCP 大多不来自 ~/.qoder/mcp.json——内置连接器随安装包分发,插件自带的连接器写在 ~/.qoder/plugins/cache/<来源>/<插件>/mcp.json。a4agent 管的是用户自定义那一份文件,用户自己加的连接器才会落进来;不去扫描内置与插件连接器是有意的边界(否则会读出几百个不可管理的条目)。想让某个 server 出现在 Qoder 端视图,用「安装 MCP」或跨端迁移把它写进这个文件。

3. 发现与聚合

「MCP 管理」页签加载时调用 /api/v1/mcp/discover,扫描九端全局与各项目级配置,把跨端同名的 server 聚合到一张卡片,并标注「已在 N 端存在」:

graph LR A[扫描九端
全局配置] --> D[归一 schema
按 name 聚合] B[扫描项目级
配置文件] --> D D --> E{同名?} E -->|是| F[合并到一张卡片
标注「已在 N 端存在」] E -->|否| G[单独一张卡片] F --> H[渲染卡片列表
env/headers 脱敏] G --> H style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style F fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

几个细节:

  • 传输归一:各家对传输类型的命名不一(如 dsh 与 pi 的 streamable-http、ZCode 省略 type 时按字段推断、OpenCode 的 local / remote),统一归一为 stdio / sse / http 三种。
  • 脱敏:server 详情的 env / headers 只回显键名,API 永不回传明文密钥;迁移读写由后端直接基于配置文件进行,前端全程见不到真实值。
  • 项目级识别:Claude Code 读 <项目>/.mcp.json,Codex 读 <项目>/.codex/config.toml,ZCode 读 <项目>/.zcode/config.json,pi 读 <项目>/.pi/mcp.json(需该项目已被 pi 信任),OpenCode 读 <项目>/.opencode/opencode.json(c);dsh 与 WorkBuddy 无项目级,Qoder 的项目级就是 Claude Code 的 .mcp.json(归 claude 端,不重复发现),TRAE 无可写明文配置、不做项目级发现。
  • TRAE 只读标注:TRAE 端的卡片会明确标注「只读」,对其执行安装 / 迁移 / 删除会被闸门拒绝并提示到 TRAE 界面操作(见第 2 节说明)。

4. 安装 MCP 服务

除迁移已有 server 外,「安装 MCP」还能在任意应用从零新建或批量导入 server(自 0.2.3 起),安装后立即出现在卡片列表并自动匹配功能介绍。

4.1 从零新建

点「安装 MCP」选择目标应用(Claude Code / Codex / dsh / ZCode / pi / Qoder / OpenCode / WorkBuddy,写入该应用全局配置;TRAE 只读、不在可选之列)与传输类型(stdio / http / sse,按目标端能力自动过滤,如 Codex 仅 stdio、pi 与 OpenCode 无 sse、WorkBuddy 三种都认),再填写命令 / 参数 / 环境变量(stdio)或地址 / 请求头(http / sse)即可。安装走各端原生渲染与原子写:目标端同名 server 已存在会明确拒绝(可改用迁移或先删除),既有 server 与其他配置键原样保留。

Qoder 不提供项目级安装入口:它的项目级文件与 Claude Code 是同一个 <项目>/.mcp.json,归 claude 端托管,两端各写一次只会互相踩写——迁到 Claude 项目级即 Qoder 项目级同时生效。OpenCode 有自己的项目级文件,安装时按 6.2 的路径优先级写入。

4.2 JSON 批量导入

把已有的 MCP 配置片段直接粘贴进来一次装多个,兼容三种格式:

  • mcpServers 顶层键的完整配置片段;
  • 名称作键的 server 字典;
  • 单个 server 对象。

批量导入逐条独立:单条失败(同名冲突、目标端不支持该传输等)不中断其余,并逐条报告成功 / 失败结果。

graph LR A[安装 MCP] --> B{安装方式} B -->|从零新建| C[选目标应用+传输类型
填命令或地址] B -->|JSON 批量导入| D[粘贴配置片段
兼容三种格式] C --> E[逐条原生渲染
原子写入全局配置] D --> E E --> F{单条成功?} F -->|是| G[出现在卡片列表
自动匹配功能介绍] F -->|否| H[报告该条失败原因
不影响其余条目] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style D fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#fadbd8,stroke:#c0392b,stroke-width:2px

5. 功能介绍

每张 server 卡片显示该 server 的功能介绍,三个来源自动兜底(自 0.2.3 起):

来源 说明
内置简介库 常用 server 的预置说明,开箱即用
npm registry 实时查询 npx 形式的 server 读取其 npm 包描述,查询结果有缓存与失败兜底
手工维护 点「介绍」可自定义说明:本地持久化、跨端共享、留空即清除

6. 跨端迁移与传输能力矩阵

点击卡片的「迁移」选择源副本与目标位置(全局 / 项目),执行后把 server 的配置片段写入每个目标端:

  • 源端保留:迁移是复制而非移动,源配置文件不变。
  • 先快照再写入:目标端已有同名 server 时,旧片段先快照进回收站再写入新内容,绝不静默覆盖;写入前自动备份目标配置文件(滚动保留 5 份)。
  • 严格校验:迁移按传输能力矩阵校验源传输类型是否被目标端支持,不兼容的组合整对失败并留日志,不静默降级:
graph LR A[选择源 server
含传输类型] --> B{目标端支持
该传输?} B -->|否| C[整对失败
写入迁移日志] B -->|是| D{目标端已有
同名 server?} D -->|是| E[旧片段快照
进回收站] D -->|否| F[直接写入] E --> G[写入目标配置文件
前先备份] F --> G G --> H[记录迁移日志] C --> H style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#fadbd8,stroke:#c0392b,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

6.1 传输能力矩阵

目标端 支持的传输 配置文件 项目级
Claude Code stdio / sse / http ~/.claude.json 支持 .mcp.json
Codex 仅 stdio ~/.codex/config.toml 支持
dsh stdio / streamable-http cordis.patch.yml 不支持
ZCode stdio / sse / http ~/.zcode/cli/config.json 支持
pi stdio / streamable-http ~/.pi/agent/mcp.json 支持(需项目被信任)
Qoder stdio / sse / http ~/.qoder/mcp.json 不托管(复用 Claude 的 .mcp.json)
OpenCode stdio / streamable-http ~/.config/opencode/opencode.json(c) 支持(.opencode/ 内)
WorkBuddy stdio / sse / http(http 写回记作 streamableHttp) ~/.workbuddy/mcp.json 不支持(仅全局)
TRAE 只读发现(不可作为安装 / 迁移目标) 加密内部库(明文侧仅运行时缓存) 不支持

6.2 各端写入细节

  • dsh:MCP server 挂在 @deepseek-ai/dsh-mcp-client 插件条目下,重写时保留该插件其他非管理条目与其余插件;条目 id 按 server 名安全化(仅保留字母数字与 - / _)。
  • ZCode:官方 schema 严格(未知键会被丢弃),a4agent 只写规范字段(type / command / args / cwd / env / url / headers / enabled / timeoutMs);type 可省略,有 command 推断 stdio、有 url 推断 http/sse。迁移到 ZCode 的 server 会被客户端自动连接。
  • Codex:仅 stdio——把 sse / http 传输的 server 迁到 Codex 会整对失败,改用本地桥接(如 npx 起 stdio 包装)后再迁。
  • pi:mcp.json 与 Claude Code 同构(顶层 mcpServers),但明确拒绝 legacy SSE(type: "sse" 会被判废),迁移到 pi 的 sse 条目整对失败并留日志。pi 另有自有键 exposure / toolExposure / enabled / timeout / auth / oauth 决定工具如何暴露给模型,a4agent 读写时无损保留这些键与顶层 autoEnableCodemode;server 名只接受字母、数字、_、-,含中文或点号的名字会在迁移 / 安装时被明确拒绝(写出即废条目),项目级文件不接受 auth 键,写入时自动剔除并记录日志。
  • Qoder:~/.qoder/mcp.json 与 Claude Code 同构(type 认 stdio / sse / http / streamable-http),自有键是 disabled(在 Qoder 界面关掉某个 server 的开关,注意不是 enabled)、timeout、authType,读写时一并无损保留。项目级与 Claude Code 共用同一个 <项目>/.mcp.json(Qoder 按 .mcp.json → mcp.json 的顺序查找),所以 a4agent 不让 Qoder 端再接管项目级文件——迁到 Claude 项目级即 Qoder 项目级同时生效。运行时镜像 %APPDATA%\Qoder\SharedClientCache\extension\local\mcp.json 与 ~/.qoder/mcp-router.json 是进程内状态,既不读也不写、不纳入备份。
  • OpenCode:配置在 mcp.servers 下,只有两种传输——local(stdio)与 remote(Streamable HTTP),没有 legacy SSE 的位置,sse 来源的条目整对失败并留日志。三处形状差异由 a4agent 抹平:命令是单个数组(可执行与参数合一,写回时才拆开)、环境变量键叫 environment(不是 env)、启停开关叫 disabled;codemode / timeout / protocol / oauth 等自有键无损保留。项目级注意 .opencode/ 内的配置覆盖项目根目录的同名文件(0.6.1 修正过探测顺序,此前会写进一个永不生效的文件)。
  • WorkBuddy:~/.workbuddy/mcp.json 与 Claude Code 同构(顶层 mcpServers),stdio / sse / http 三种传输都认,但 http 传输的 type 拼写是驼峰 streamableHttp——写回必须还原该拼写,否则端上认不出。timeout 等自有键逐条目无损保留(重写整表时原样写回,丢了它慢启动的 server 会超时失败);重写只替换 mcpServers 子树,文件里其余顶层键原样保留;读取失败即中止写入(与 Qoder 同款中止原则,绝不按空配置重建)。没有工作区级 MCP 配置,项目级不支持。
  • TRAE:只读端——用户级 MCP 配置在加密内部库(非标准 SQLite),明文侧只有运行时缓存(~/.trae-cn/mcps/<工作区>/<agent>/<server>/ 下的 SERVER_METADATA.json 与 tools/*.json),缓存里没有连接参数。a4agent 读缓存做发现并标注「已在 N 端存在」;安装 / 写入 / 删除 / 迁移闸门全部拒绝并如实标注只读,需要变更请在 TRAE 界面操作。

OpenCode 的配置文件是 JSONC(可带注释与尾逗号)。a4agent 写入的是标准 JSON(合法 JSONC),能正确读取带注释的既有文件,但该文件上的手写注释会在写入时丢失——这是「整子树替换」的固有取舍。介意的话改用 OpenCode 自己的界面配置即可;配置读取失败时 a4agent 会中止写入,绝不按空配置重建(那会清空你的 model / agents / permissions)。

7. 回收站与安全

  • 被替换 / 删除的 server 配置片段快照进回收站:磁盘快照存于数据目录 mcp_recycle\,数据库 mcp_trash 表记录原配置文件路径等恢复信息,30 天内可恢复原位或彻底删除,过期条目访问时惰性清理。
  • 快照中的 env / headers 用 DPAPI 加密落盘,恢复时解密写回——保证回收站这个"垃圾桶"里也没有明文密钥;0.6.3 起恢复时若解密失败会立即中止并报错,不再静默清空凭证(避免把坏数据写回原配置文件)。
  • 每次成功或失败的迁移写入 McpMigration 日志(时间、server、传输类型、源、目标、结果),「迁移日志」弹窗按新到旧查看。
  • 发现、内容预览、回收站接口对敏感字段全程脱敏。

8. 接口一览

接口 方法 用途
/api/v1/mcp/discover GET 全量发现与聚合
/api/v1/mcp/servers POST 从零新建安装 server(自 0.2.3 起)
/api/v1/mcp/servers/import POST JSON 配置片段批量导入(自 0.2.3 起)
/api/v1/mcp/descriptions GET / PUT 读取 / 维护 server 功能介绍(自 0.2.3 起)
/api/v1/mcp/projects GET 项目级配置文件扫描列表
/api/v1/mcp/migrate POST 跨端迁移(源端保留,冲突先入回收站)
/api/v1/mcp/migrations GET 迁移日志(新到旧)
/api/v1/mcp/delete POST 删除某端某 server(配置片段移入回收站)
/api/v1/mcp/content GET 读取 server 详情(脱敏)供预览
/api/v1/mcp/trash GET 回收站列表(含惰性清理提示)
/api/v1/mcp/trash/{id}/restore POST 恢复回收站条目到原位置
/api/v1/mcp/trash/{id} DELETE 彻底删除回收站条目

9. 常见问题

问:迁移会把源端的 MCP server 移走吗?

答:不会。迁移把配置片段复制到目标端,源端配置文件保持不变;目标端已有同名 server 时旧片段先进回收站,不静默覆盖。

问:为什么把 sse 的 server 迁到 Codex 会失败?

答:Codex 的 MCP 客户端仅支持 stdio 传输,sse / http 组合不满足传输能力矩阵,整对失败并写入日志。想给 Codex 用,请在源端改用 stdio 桥接方式。

问:回收站快照里的密钥安全吗?

答:安全。快照由 mcp_recycle\ 目录承载,其中的 env / headers 在落盘前经 Windows DPAPI 加密,恢复时才解密写回;同时所有接口响应只回显键名,不返回任何明文。

问:mcp_trash 里的旧条目会不会一直占用磁盘?

答:不会。回收站条目超过 30 天后在下次访问回收站时惰性清理,并在返回结果中提示本次清理数量;也可随时对单条执行「彻底删除」。

问:批量导入时有一条格式不对会怎样?

答:逐条独立处理——格式正确且无冲突的条目正常安装,失败的那条单独报告原因(同名冲突、目标端不支持该传输等),不会中断或回滚其余条目;修好失败的条目后可以单独再导。

问:卡片上的功能介绍不准怎么办?

答:点卡片上的「介绍」手工维护说明即可,自定义内容本地持久化、跨端共享;清空则恢复自动识别(内置简介库或 npm 包描述)。

问:Qoder 里明明连着好几个 MCP,为什么 a4agent 的 Qoder 卡片是空的?

答:两者并不矛盾。a4agent 管理的是用户自定义那一份 ~/.qoder/mcp.json;Qoder 会话里实际连着的多数连接器来自安装包内置的连接器与插件自带的 mcp.json,都不属于用户配置文件。想让某个 server 出现在 Qoder 端视图,用「安装 MCP」或跨端迁移把它写进 ~/.qoder/mcp.json。

问:为什么迁到 pi 的 server 名字被拒绝了?

答:pi 的 server 名只接受字母、数字、_、-,含中文或点号的名字写出即成废条目,因此 a4agent 在安装 / 迁移时明确拒绝并给出提示,改名后再迁即可。

问:OpenCode 的配置文件里有手写注释,会被弄丢吗?

答:会。OpenCode 的配置是 JSONC,a4agent 写入的是标准 JSON(合法 JSONC),能正确读取带注释的既有文件,但整子树替换时注释会丢失。介意的话请在 OpenCode 自己的界面里改;读取失败时 a4agent 会中止写入而不是按空配置重建。

问:WorkBuddy 的 MCP 配置为什么只能装到全局?

答:WorkBuddy 没有工作区级 MCP 配置文件,能力矩阵里它就是仅全局——界面不会给出「写进一个它永远不读的文件」这种选项。它条目里自带的 timeout 等自有键在 a4agent 读写往返中原样保留,http 传输写回时按它的驼峰拼写 streamableHttp 记录。

问:为什么不能把 MCP 安装或迁移到 TRAE?

答:TRAE 的用户级 MCP 配置保存在加密内部库,明文侧只有运行时缓存,缓存里没有连接参数——写一个「它读不到」的文件只会造成假象。因此 a4agent 对 TRAE 只做只读发现(如实列出它的 server 并标注「已在 N 端存在」),安装 / 迁移 / 删除闸门全部拒绝,变更请在 TRAE 自己的界面里操作。