上礼拜往本机加了一个新的 MCP server又双叒叕走了一遍熟悉流程先在 Claude Code 里翻配置再去改 Codex 的 TOML接着打开 Cursor 的 mcp.json最后还得手动给我的自研 Agent内部代号 Hermes Agent备一份。说实话MCP 这个协议已经帮我们把“工具怎么接入”这件事统一了结果每个 Agent 的配置文件还是各写各的技能文件更是散落得到处都是——同一套最佳实践我在三个工具里维护了三份还经常不同步。折腾多了我干脆搭了一套本机全局的配置同步方案一套注册表、一个生成脚本、几个符号链接Claude Code / Codex / Cursor / Hermes Agent 全部吃同一份 MCP 配置、同一份技能目录。新增 MCP 不用再逐个 Edit 配置文件技能目录里丢一个新技能所有工具立刻可用。这篇就把完整思路和可复现的做法写出来给同样被多 Agent 配置折磨的人一个可以直接抄的作业。1. 多 Agent 环境下的配置分裂问题出在三层1.1 MCP 统一了协议却没有统一配置文件MCPModel Context Protocol解决的是“Agent 如何调用外部工具”的标准化问题。以前每接一个工具要给每个 Agent 写一套自定义对接代码现在只需要给 MCP server 配好 command、args、环境变量Agent 就能通过协议跟它通信。但它只统一到“协议”这层没统一到“配置”这层。每个 Agent 都有自己接受的配置格式和存放位置Claude Code 认 JSONCodex 认 TOMLCursor 有自己的 mcp.json我这边自研的 Hermes Agent 又是一个约定好的目录结构。同一个 MCP server想在四个工具里都能用就得把同样的信息分别写四遍。1.2 我本机实际维护过的四套配置先列一份真实的本机清单大家可以对照一下自己是不是也处于这个状态工具配置位置配置格式MCP 配置字段技能/指令形态Claude Code~/.claude.json用户级、.mcp.json项目级JSONmcpServers~/.claude/skills/下的 SKILL.md带 YAML frontmatterCodex~/.codex/config.toml、项目根AGENTS.mdTOML[mcp_servers.*]AGENTS.md风格说明文档Cursor.cursor/mcp.json项目级全局规则在设置目录JSONmcpServersRules.mdc 文件带 frontmatterHermes Agent自研~/.hermes/自定义目录自定义自研约定自定义技能目录这里有个很容易踩的细节Claude Code 的“用户级 MCP 配置”其实藏在~/.claude.json这个文件里而这个文件同时还存了会话历史、项目状态等一堆东西。最初我图省事直接整体写这个文件结果把会话记录弄丢过一次。后来改成脚本只合并mcpServers字段才算是稳了。1.3 配置分裂的直接代价四套配置带来的问题不是简单的“多写几行”第一时间成本。接一个新 MCP光配置就要改四个文件每个文件格式还不一样复制粘贴也得小心翼翼避免把 TOML 内容贴进 JSON。第二出错概率。我试过一次把 Codex 的 TOML 数组语法写成了 JSON 的数组语法启动直接报错找原因找了十分钟。第三技能不同步。Claude 侧更新了某个技能文件Cursor 那边还是旧版本同一个操作在两个工具里表现不一致。这个问题最隐蔽因为不报错只是结果有细微差异。所以“统一配置”不是锦上添花而是多 Agent 重度使用场景下的刚需。2. 统一配置的两块基石用户级配置与符号链接2.1 配置继承顺序是“本机全局”的合法依据几乎所有 CLI 类的 Agent 都有类似的配置优先级内置默认值 用户级配置 项目级配置。Claude Code 会先加载用户级设置再在项目目录里找.claude/下的覆盖项Codex 类似用户配置在~/.codex/项目配置在项目根Cursor 的 MCP 配置也可以分项目级和全局级。这个继承顺序就是整套方案的合法性基础把个人常用的 MCP server 和技能放到“用户级”这一层它们就在本机所有项目里全局生效同时不污染任何一个项目的仓库。项目级配置依然保留专门放团队协作需要的那些 server 和规则。两者隔离互不干扰。2.2 符号链接让所有 Agent 读到同一份数据做同步的方案无非三种复制、硬链接、符号链接。复制是最差的选择因为改源文件后每个副本都要重新手动同步过不了多久就又分叉了。硬链接在同一文件系统内可以但跨文件系统比如 Windows 上 C 盘和 D 盘会失效。符号链接symlink是我的选择。它本质是一个“快捷方式”多个路径指向同一个真实文件或目录Agent 读 A 路径时拿到的就是源目录里的最新内容不需要任何同步动作。我这边 macOS 上一条ln -s就搞定Windows 上需要New-Item -ItemType SymbolicLink或mklink /D前提是开启开发者模式或者以管理员身份执行。用生活里的话说以前我是把同一份文档复印四份分发给四个同事现在我在四个同事的桌上放了一张写有同一个档案柜位置的便签。档案柜里的内容变了四个同事看到的自然都是新的。2.3 所谓“0 配置”不是没有配置而是配置只写一处标题里写了“0 配置”这个话容易引起误解。MCP server 的注册信息不可能凭空消失你总得告诉系统“这里有个 server它用什么命令启动”。真正的 0 配置是Agent 侧不需要你再动任何手工配置文件。我的做法是引入一个“统一注册表”文件所有 MCP server、技能目录都登记在这一个文件里然后用脚本根据注册表自动生成各个 Agent 需要的那四份配置。日常操作从“改四个文件”变成“改一个文件”其余全部自动化。这就是 0 配置的真实含义配置收敛到一处剩下交给程序。3. 落地实现一套目录结构、一个注册表、一个生成器3.1 目录设计源文件、注册表、生成物分开放先看我最终采用的目录结构~/.agent-sync/ ├── registry.json # 统一注册表全方案的唯一人工维护入口 ├── skills/ # 所有技能的源文件SKILL.md 关联脚本 ├── generated/ # 生成器输出的各 Agent 配置不手工编辑 ├── scripts/ │ └── generate.py # 注册表 - 各工具配置的生成器 └── logs/ └── sync.log # 每次生成的变更日志设计原则很简单人工只碰registry.json和skills/generated/完全是机器产物改名字、改路径都无所谓重新生成一遍即可。这套结构花了最多心思的不是“怎么写”而是“怎么让边界清晰”。3.2 统一注册表的字段设计registry.json是我定义的唯一事实源核心按 MCP server 和技能两大部分组织。一个经过实战打磨的例子长这样{ mcpServers: [ { name: github, description: GitHub API tools for search and issues, command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_TOKEN: { fromEnv: GITHUB_TOKEN } } }, { name: filesystem, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ~/Downloads, ~/Documents] } ], skills: { sourceDir: ~/.agent-sync/skills, targets: { claude: ~/.claude/skills, cursor: ~/.cursor/rules, hermes: ~/.hermes/skills } } }几个字段的用意要说明一下env里我特意不写死密钥而是用fromEnv引用当前 shell 的环境变量GITHUB_TOKEN。这样registry.json本身可以安全地纳入 Git 管理不会把个人 token 泄露进仓库。生成器在出配置的时候再去解析当前环境变量把解析后的值写入生成的配置文件里——如果环境变量不存在生成器会明确报错提示而不是生成一个启动即挂的配置。skills.targets记录每个 Agent 的技能目录应该软链接到哪个位置。之所以在注册表里统一声明而不是写死在脚本里是因为这些路径在不同系统上差异很大Windows 的用户目录路径、macOS 的~/Library/Application Support都有可能。3.3 生成器核心逻辑别整体覆盖只合并关键字段生成器的核心逻辑不复杂难在“合并”而不是“覆盖”。以 Claude Code 为例我不能把整个~/.claude.json覆盖掉那里面还有会话数据和项目状态。正确做法是用 Python 读现有文件只更新mcpServers字段其他全部保留。#!/usr/bin/env python3 import json, os, shutil, subprocess from pathlib import Path HOME Path.home() SYNC_ROOT HOME / .agent-sync def load_registry(): with open(SYNC_ROOT / registry.json) as f: return json.load(f) def resolve_env(env_spec): resolved {} for key, value in (env_spec or {}).items(): if isinstance(value, dict) and fromEnv in value: src os.environ.get(value[fromEnv]) if not src: raise RuntimeError(fMissing required env var: {value[fromEnv]}) resolved[key] src else: resolved[key] value return resolved def merge_claude_code(registry): claude_json HOME / .claude.json data {} if claude_json.exists(): data json.loads(claude_json.read_text()) servers {} for srv in registry[mcpServers]: servers[srv[name]] { command: srv[command], args: [expand_user(a) for a in srv.get(args, [])], env: resolve_env(srv.get(env, {})) } data[mcpServers] servers # 只动这个 key claude_json.write_text(json.dumps(data, indent2, ensure_asciiFalse)) def merge_codex(registry): config_path HOME / .codex / config.toml config_path.parent.mkdir(parentsTrue, exist_okTrue) lines [] if config_path.exists(): lines config_path.read_text().splitlines() # 简单处理定位 [mcp_servers] 段并替换实际项目里建议用 toml 解析库 for srv in registry[mcpServers]: lines.append(f\n[mcp_servers.{srv[name]}]) lines.append(fcommand {srv[command]}) args_list [expand_user(a) for a in srv.get(args, [])] lines.append(fargs {format_toml_array(args_list)}) config_path.write_text(\n.join(lines) \n) if __name__ __main__: reg load_registry() merge_claude_code(reg) merge_codex(reg) link_skills(reg[skills])这个脚本故意保持了“看得懂”的程度。真实工程里Codex 的 TOML 合并建议直接用 Python 的toml库做结构化读写而不是文本行操作——我这里用文本追加只是为了表达核心思路大家自己落地时优先用成熟的解析库。3.4 一次性部署命令序列把整个方案从零搭起来按下面的顺序操作# 1. 创建目录骨架 mkdir -p ~/.agent-sync/{skills,generated,scripts,logs} # 2. 写 registry.json参照上文示例 # 3. 创建各 Agent 技能目录的初始软链接 # 先备份已有技能目录如果有 [ -d ~/.claude/skills ] mv ~/.claude/skills ~/.claude/skills.bak mkdir -p ~/.claude/skills ln -s ~/.agent-sync/skills ~/.claude/skills/agent-sync # 4. 运行生成器 python3 ~/.agent-sync/scripts/generate.py # 5. 重启对应 Agent 验证 claudeln -s ~/.agent-sync/skills ~/.claude/skills/agent-sync这行值得解释一下我没有把~/.claude/skills整个替换成软链虽然技术上可行而是建了一个子目录软链agent-sync。这样 Claude Code 自带的默认技能目录还在不会因为我的操作而影响工具自身行为同时我在~/.agent-sync/skills/里新增技能Claude 侧立刻就能看到。3.5 日常新增 MCP server 的操作节奏搭完这套体系之后我新增一个 MCP server 的流程变成了在registry.json里追加一个 server 条目一分钟。运行python3 ~/.agent-sync/scripts/generate.py。重启对应的 Agent或重载 MCP 配置。整个过程不需要再碰任何工具的原生配置文件。如果某个 Agent 报“找不到配置”我第一反应是检查注册表里这个 server 的command和args是否写对了而不是怀疑其他地方——排查范围一下子缩到一个小文件里省了很多事。4. 各 Agent 的配置差异与适配细节4.1 Claude Code合并mcpServers字段Claude Code 的用户级配置分布在两个地方MCP server 清单在~/.claude.json的mcpServers字段里技能目录默认是~/.claude/skills/部分版本也支持项目级.claude/skills/。处理时要特别小心~/.claude.json是会话和项目状态的大杂烩生成器必须走“读整个文件 - 只改mcpServers- 写回整个文件”的路线。我最初版本就是漏了这一步导致每次生成都覆盖掉会话记录后来加了字段级合并才算稳。技能目录用软链接方案我实测对SKILL.md的识别没问题工具会把软链目录当成普通技能目录扫描。4.2 CodexTOML 格式与 AGENTS.md 指令Codex 的 MCP 配置在~/.codex/config.toml格式是[mcp_servers.github] command npx args [-y, modelcontextprotocol/server-github]生成器要把 JSON 结构转成这个 TOML 片段。注意 TOML 的数组语法是[a, b]不是 JSON 那样带尾逗号生成时别偷懒用简单字符串拼接最好用toml库输出避免转义问题。Codex 里“技能”的表现形式不是独立的技能文件而是AGENTS.md这种说明文档。所以我处理 Codex 的方式略有不同把~/.agent-sync/skills/里适合 Codex 的知识性技能比如编码规范、工具使用说明合并生成一份~/.codex/AGENTS.md而不是做目录软链。这里的取舍是Claude 的技能强调“可调用的能力包”Codex 的 AGENTS.md 更强调“上下文说明”两者语义不完全对等。4.3 Cursor项目级 mcp.json 与用户级规则的方向Cursor 的 MCP 配置默认在项目目录.cursor/mcp.json这样做的后果是你在 A 项目里配了一个 MCP切到 B 项目就没了。要想全局生效要么每次生成器往各个项目里同步要么确认你的 Cursor 版本支持用户级 MCP 配置。我的方案是在部署时一次性往常用项目的.cursor/mcp.json写入生成结果同时在registry.json里维护一份“需要同步的 Cursor 项目列表”生成器每次把这些项目全部同步一遍。Cursor 的全局 Rules 则放在对应系统设置目录里用法跟 Claude 类似做一个子目录软链即可。我这里要明确一个负责任的提醒Cursor 各个版本的全局配置路径变化比较频繁部署前建议先实测一次你那个版本的读取路径再决定软链落到哪里。4.4 Hermes Agent自研 Agent 直接读注册表自研 Agent 最大的好处是配置格式你自己定。Hermes Agent 我压根不做生成环节直接在代码里让 MCP manager 读取~/.agent-sync/registry.json作为唯一来源。新增 server 只需写一次注册表Hermes 下次启动自动发现。其他自研 Agent 接入时也同理——配置文件格式既然是自定义的直接消费 registry 就是最省事的方式。这也算是整套方案的“自举”标准是统一的越晚接入的工具反而越简单。4.5 环境变量与路径的归一化处理适配过程中最容易忽视的雷是路径问题。注册表里我写了~/Downloads这种带波浪号的路径不同 Agent 解析这条路径的行为不一有的能自动展开有的原样传给子进程导致启动失败。所以生成器里必须有统一的expand_user步骤把所有路径规范成绝对路径再生成。同理环境变量里的 token 如果是通过 shell 配置的有的 Agent 启动时能继承有的需要写到配置里。我在注册表里用fromEnv标记生成时统一解析规避了“同一个变量名这个 Agent 认那个 Agent 不认”的混乱。5. 技能文件的跨 Agent 同步5.1 技能的常见载体都是带 frontmatter 的 Markdown先说一个观察Claude Code 的 SKILL.md、Cursor 的 Rules.mdc 文件、很多开源 Agent 的技能包本质都是“带 YAML frontmatter 的 Markdown”。frontmatter 里包含 name、description、globs 之类元信息正文是给模型读的推理步骤或指令。这个共性就是统一技能格式的基础。我把技能的源文件全部放在~/.agent-sync/skills/技能名/SKILL.md每个技能一个目录目录里可以带参考脚本或资源文件~/.agent-sync/skills/ ├── code-review/ │ ├── SKILL.md │ └── review-checklist.json ├── test-coverage/ │ ├── SKILL.md │ └── templates/ └── database-troubleshoot/ └── SKILL.md5.2 源目录如何分发到各 Agent分发方式取决于目标 Agent 的技能目录结构Claude Code软链~/.claude/skills/agent-sync指向源目录它自动扫描子目录里的 SKILL.md。Hermes Agent直接配置技能搜索路径包含~/.agent-sync/skills。Cursor如果源技能带 frontmatter可以做兼容规则文件软链某些规则专用字段比如 globs 的匹配语法因工具而异需要转换。Codex不走目录软链而是用生成器把技能描述片段汇总进AGENTS.md让模型在上下文里感知。这里必须讲一个实操教训软链整个技能目录虽然省事但有的工具比如某些版本的自研 Agent会在技能目录里写入索引缓存或者“最近使用”标记这样会反过来污染源目录。稳妥的折中方案是只让工具对源目录有读权限或者接受源目录里出现缓存文件并在.gitignore里忽略它们。我在源目录外挂.gitignore就是为了挡住这些垃圾文件否则 Git 仓库会越来越脏。5.3 需要格式转换时写一个小转换器如果某个 Agent 对技能格式要求严格比如 Cursor 的 Rules 必须带metadata.author之类的专用字段直接软链同一个文件会识别失败。这时生成器里加一个转换函数def convert_skill_for_cursor(src_skill_md, out_mdc): data parse_frontmatter(src_skill_md) # 读 SKILL.md 的 YAML metadata { name: data.get(name), description: data.get(description), globs: data.get(globs, **/*), } with open(out_mdc, w) as f: f.write(---\n) f.write(yaml.dump(metadata)) f.write(---\n\n) f.write(read_body(src_skill_md))转换器不复杂但能解决真实障碍我之前直接把 SKILL.md 复制成 .mdc结果 Cursor 一直不识别就是因为缺了新版要求的关键元数据字段。规则是凡是跨工具同步的技能先确认目标工具对 frontmatter 字段的最小要求再决定是软链还是转换。5.4 技能和 MCP 的联动校验我踩过的一个坑是技能文件里引用了某个 MCP 工具比如让模型调用 GitHub 搜索接口但这个 MCP server 从来没在注册表里登记过。结果模型在 Claude Code 里可以执行在 Cursor 里直接找不到工具报错信息还不明确。后来我在生成器里加了一个“引用完整性检查”扫描所有 SKILL.md 正文提取形如mcp__server__tool的工具引用再去 registry 的 MCP server 列表里比对找不到就在日志里打警告。这个检查把技能和 MCP 两条线闭环了起来配置问题从“运行时报错”提前到“生成时报错”。6. 实测对比与避坑清单6.1 新增 MCP server 的成本变化用我本机真实维护的数据做一个对比操作改造前改造后新增一个 MCP server改 Claude Code JSON、Codex TOML、Cursor mcp.json、Hermes 配置共 4 处只改 registry.json 1 处新增一个技能分别复制/编写最多 4 份不同格式文件在 skills 目录新增一个 SKILL.md排查“这个工具跑不起来”检查 4 份配置 可能的格式错误检查 registry 对应条目 环境变量单次操作耗时8 到 12 分钟1 分钟内时间节省不是最关键的关键是心智负担轻了以前每次接新工具都如临大敌现在更像走个流程。6.2 实战中踩过的坑坑一软链目标目录不存在。第一次部署时我建软链结果 Claude 的技能目录不存在ln -s直接失败。后来脚本里统一加mkdir -p兜底。坑二Windows 上符号链接需要权限。Windows 默认不给普通用户创建软链的权限要么以管理员运行终端要么在“开发者模式”里打开相关开关。跨盘符建链也会失败需要保证软链和源目录在同一卷内。坑三有的工具升级后配置字段改名。我经历过的典型变化某个版本把 MCP 配置从mcpServers改成mcp_servers。应对办法是生成器里加一个“适配层”先用实测确认当前版本的字段再把注册表里的标准字段转成目标字段。所以注册表用一个抽象结构而不是直接照搬某工具的 schema这很重要。坑四配置缓存。改完配置不重启 Agent很多时候不生效。Claude Code 一般需要重启会话Cursor 需要重新加载窗口Codex 有时需要退出重进。我把“重启验证”写进了部署脚本的提示里避免自己忘了。坑五不要整体覆盖用户级配置文件。这个已经强调过是整套方案里最容易造成数据损失的操作。凡是和会话状态、历史记录混在一起的配置文件一律字段级合并。坑六远程开发和容器环境需要单独处理。这个方案默认“本机单一用户”如果你用 VS Code Remote 或者其他方式连到容器/远程机器本机用户目录和远程路径不是一回事软链要针对远程环境重新配置。我目前对远程容器还是用项目级配置不强行全局同步。6.3 什么场景不适合这套方案这套方案适合“单人单机全 Agent 统一维护”的场景。它不适合团队协作项目项目级配置要保留在仓库里个人 MCP 不应该进入团队仓库否则队友拉到你的 server 配置直接启动失败。保密性要求高的环境registry.json虽然不存真实 token但 server 名称、用途本身可能泄露业务信息别随便传到公共仓库。工具版本跨度大的环境不同大版本的 Agent 对配置 schema 兼容性很差适配层工作量大可能得不偿失。6.4 进阶把生成器变成一条命令最后分享一个让体验更丝滑的技巧把整个流程封装成一个 alias 或者脚本命令。alias agent-syncpython3 ~/.agent-sync/scripts/generate.py echo Done. Restart agents.以后所有的新增 server、新增技能、技能引用校验全部变成agent-sync一句话的事。我的registry.json和skills/目录都放进了 Git 仓库每次改动都有历史记录哪次配置出问题可以git diff快速回滚。跑得时间久了我最大的体会是这套方案真正解决的问题不是“少写几行配置”而是把 AI 编程工具的配置从“各工具自治”变成了“统一治理”。当你同时用多个 Agent 写代码时MCP 配置的维护成本和技能版本的分叉是比想象中更耗精力的隐形负担。我现在的日常已经稳定在“注册表改一条 重启 继续写码”的节奏上希望这篇分享也能帮你把类似的负担卸下来。