ZT-003教程TESTED

MCP 是什么？Claude Code + Codex 双客户端从配置到实战

MCP 可以理解为给 AI Coding Agent 接外部能力的统一插口。本文拿同一个公开 Server 对照 Claude Code 与 Codex，先把配置跑通，再用 Tool 调用验证链路。

作者
AI折腾所
发布
更新
阅读
约 6 分钟
  • MCP
  • Claude Code
  • Codex
  • AI Coding
MCP Server 在 Claude Code 与 Codex 中配置和调用的对照示意

本文按当前环境记录：Claude Code 2.1.266，Codex CLI 0.142.5。命令和输出以这两个版本为准；第三方账号、Token 和私人路径不写入示例。两端均已连接同一个 Server，并完成 echo Tool 的真实调用。

最终你会得到什么

完成本文后，你会把同一个 server-everything MCP Server 分别注册到 Claude Code 和 Codex，确认两端能够发现它，并用相同输入调用同一个 echo Tool。这样可以直接看清：协议和 Server 可以共用，但两端的配置入口与文件格式不同。

MCP 到底是什么

MCP（Model Context Protocol）不是 Claude Code 的专属插件机制，而是一套让 AI 客户端连接外部能力的公开协议。可以把它想成“给 AI Coding Agent 接外部工具的一套统一插口”：客户端负责发起请求，Server 负责提供能力。

因此，MCP 解决的是连接方式不统一的问题。文件搜索、网页查询、计算或项目资料，都可以由不同 Server 提供；客户端不需要为每个服务重新发明一套调用格式。

MCP 里的几个核心角色

  • MCP Client：连接 Server 的程序。本文里的 Claude Code 和 Codex 都是 Client。
  • MCP Server：真正提供外部能力的进程或远程服务。它可以由任何人实现，不属于某个客户端品牌。
  • Tool：可以被调用的动作，例如示例 Server 的 echo。
  • Resource：可读取的上下文资源，例如文档、记录或 URI 对应的数据。
  • Prompt：Server 提供的可复用提示模板，用来约定一类任务的输入方式。

记住这一层关系就够了：Claude Code / Codex 是入口，能力在 MCP Server；Tool、Resource、Prompt 是 Server 暴露出来的不同能力类型。

MCP 负责把外部能力接进客户端；Skill 更适合固化某类任务的说明和流程。如果你还没分清两者，可以先看 Claude Code Skills 完整教程，本篇不再重复 Skills 的安装和目录规则。

为什么同一个 MCP 可以给 Claude Code 和 Codex 用

只要两个客户端都支持同一种 MCP 传输方式（本例使用本地 stdio），同一个 Server 就可以被两边启动。协议层可以共用，但配置文件不能直接照搬：Claude Code 使用 JSON 配置和 scope，Codex 使用 config.toml 的 [mcp_servers.<name>] 表。

这也是本文的对照方法：固定 Server、命令、参数和测试输入，只改变注册客户端。

双客户端实测：server-everything

为了避免把个人数据接入实验，本文选择公开的 @modelcontextprotocol/server-everything 作为示例 Server。它通过 npx 启动，不需要数据库或私人账号，并提供可演示的 echo Tool。第一次运行会由 npm 下载包，请先确认本机可以访问 npm registry。

npx -y @modelcontextprotocol/server-everything

成功标准不是“命令没有立刻退出”，而是：客户端列出 Server、完成健康检查、能看到 echo，并返回与输入一致的结果。

Claude Code 怎么配置 MCP

1. 用 CLI 注册

当前版本支持直接添加 stdio Server：

claude mcp add --scope user demo-everything -- npx -y @modelcontextprotocol/server-everything

--scope user 表示写入用户级配置。需要只对当前项目生效时，可改用 --scope project；如果当前版本或项目策略不接受某个 scope，以 claude mcp add --help 的实际输出为准。不要把带 Token 的环境变量直接贴到文章或 Git。

2. 查看与确认连接

claude mcp list
claude mcp get demo-everything

在本文记录的版本中，正常输出包含 demo-everything ... Connected；get 同时显示 Scope: User config、Type: stdio、Command: npx 和参数。list 会做健康检查；看到 Pending approval、Disconnected 或 Failed 时，先不要调用 Tool。

Claude Code 终端中 demo-everything MCP Server 显示 Connected 状态
`claude mcp list` 与 `get` 均显示 demo-everything 已通过 stdio 连接。

3. 查看并调用 Tool

在 Claude Code 会话中，要求它列出 demo-everything 的 MCP 工具，然后调用 echo，输入固定文本：

请使用 demo-everything 的 echo Tool，输入：MCP dual client test

实际调用中，Claude Code 记录了 demo-everything Tool 调用，并返回 Echo: MCP dual client test。核对 Tool 名、输入和返回文本三部分，可以避免把普通对话回复误判成 MCP Tool 调用。

Claude Code 调用 demo-everything 的 echo Tool 并返回 MCP dual client test
Claude Code 使用固定输入调用 echo Tool，返回文本与输入一致。

Codex 怎么配置 MCP

这里假设 Codex 已经能正常发起模型请求。如果你还需要配置第三方 Provider、base_url 或 API Key，先按 Codex OpenAI Compatible API 切换教程 跑通请求链路；本篇只处理 MCP Server。

1. 用 CLI 添加

Codex CLI 的等价命令是：

codex mcp add demo-everything -- npx -y @modelcontextprotocol/server-everything

这会写入用户级的 $CODEX_HOME/config.toml；默认情况下 $CODEX_HOME 是 ~/.codex。生成的结构相当于：

[mcp_servers.demo-everything]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

需要远程 HTTP Server 时，当前 CLI 也提供 codex mcp add 的相关选项；具体参数请先运行 codex mcp add --help，不要把 stdio 示例改写成未经验证的 url 字段。

2. 查看配置与状态

codex mcp list
codex mcp get demo-everything

在本文记录的版本中，list 显示 enabled，get 显示 transport: stdio、command: npx 和参数。Codex 的列表输出不会像 Claude Code 一样把 Server 健康状态写成 Connected；是否能在会话中看到并调用 Tool，才是下一步验证。

Codex 终端中 demo-everything MCP Server 显示 enabled 和 stdio 配置
`codex mcp get` 显示 demo-everything 已启用，传输方式为 stdio。

3. 调用同一个 Tool

在 Codex 会话中输入与 Claude Code 相同的测试要求：

Use the demo-everything MCP server echo tool with the exact text MCP dual client test.

实际调用中，Codex 记录了 demo-everything.echo 及其 message 参数，并返回 Echo: MCP dual client test。若这里出现 401 Unauthorized，应先处理 Codex 的登录或 Provider 鉴权，不要把它误判成 MCP Server 连接失败。

Codex 调用 demo-everything.echo 并返回 MCP dual client test
Codex 使用相同输入调用同一个 echo Tool，返回文本与 Claude Code 一致。

Claude Code vs Codex MCP 配置对照

项目 Claude Code Codex
MCP 协议 相同 相同
MCP Server 可共用 可共用
CLI 配置方式 claude mcp add ... codex mcp add ...
配置文件格式 JSON（由 CLI 管理） TOML
用户级配置 ~/.claude.json 的 user scope ~/.codex/config.toml（或 $CODEX_HOME/config.toml）
项目级配置 支持 project scope；另有项目 .mcp.json 机制 以项目对应的 Codex 配置和当前 CLI 策略为准，本文未单独验证项目级覆盖
查看 Server claude mcp list / get codex mcp list / get
Tool 调用 MCP Tool MCP Tool
配置能否直接复制 否，需转换为 Claude Code 格式 否，需转换为 Codex TOML

表格只写本次版本核对过的能力；尤其是项目级覆盖，不要把一边的文件路径想当然地套到另一边。

连接失败怎么排查

按链路从前往后检查：

  1. 进程启动：单独运行 npx -y @modelcontextprotocol/server-everything，确认 Node.js、npm 和网络可用。
  2. 注册位置：用 claude mcp get 或 codex mcp get 检查 command、args 是否被 shell 引号截断。
  3. 连接状态：Claude 看 Connected；Codex 看 enabled 后继续在会话中确认工具是否出现。
  4. 权限与登录：Not logged in 或 API 401 是客户端认证问题，不等于 Server 故障。
  5. Tool 输入：先用无敏感数据的固定字符串，区分“工具未发现”和“工具执行报错”。

修改配置后重新运行 list，必要时移除并重新添加：

claude mcp remove demo-everything --scope user
codex mcp remove demo-everything

管理一套 MCP 配置

给 Server 使用稳定、短小且唯一的名称；把命令和参数记录在项目文档，把密钥放在环境变量或客户端的安全存储中。团队共享的是 Server 的来源、版本和最小权限说明，不是个人完整配置文件。

跑通这个最小例子后，再把 server-everything 换成真正需要的 MCP Server，并逐项确认来源、权限和数据范围。后续可以继续学习 MCP Server 的选择与安全边界，或把已经验证的 Server 接入实际项目工作流。