让 Codex 这类 AI 编码 agent 只靠内置工具干活，一旦要查资料、读数据库、调内部服务，能力就断了——MCP（模型上下文协议）补的就是这一段：把外部工具包装成 agent 能调用的服务，接上之后会话里多出一批可用能力。第一次接的人常在两件事上卡住：传输方式选哪种、配置写在哪份文件的哪一层。这篇按接入的完整链路讲：两种传输各自适合什么场景、配置的位置与分段、装完之后怎么验证真的接上了，以及版本 pin 这个容易被忽略的细节。MCP 协议本身的来龙去脉，见MCP 是什么一篇。
两种传输：本地子进程与远端服务
MCP 服务跑起来有两条路。stdio 传输：服务作为本地子进程被启动，Codex 与它通过标准输入输出通信——配置里写的是一条启动命令，服务随会话启动而启动、退出而退出，数据不出本机，本地文件操作、本地脚本、个人数据库客户端这类工具适合走这条路。HTTP 传输：服务作为独立的网络服务运行，Codex 通过 URL 访问，团队共享的数据库网关、内部 API、SaaS 厂商提供的 MCP 端点都走这条路。选法跟着部署形态走：工具跑在你机器上就用 stdio，工具跑在别人服务器上就用 HTTP，两边混用也很常见，本地与远端服务各配各的条目。拿不准时先想一个问题：这个工具的数据要不要出网？出网且有认证，走 HTTP；不出网、随装随用，走 stdio。
| 传输 | 服务怎么跑 | 数据走向 | 条目里写什么 | 典型场景 |
|---|---|---|---|---|
| stdio | 作为本地子进程随会话启动、随会话退出 | 不出本机 | 启动命令与参数 | 本地文件操作、本地脚本、个人数据库客户端 |
| HTTP | 作为独立网络服务运行，通过 URL 访问 | 出网，通常带认证 | URL 与认证信息 | 团队共享的数据库网关、内部 API、SaaS 厂商端点 |
| 两者混用 | 同一份 config.toml 里两种条目并存 | 本地不出网、远端出网，各走各的 | 各配各的条目，都挂在 mcp_servers 段下 | 本地脚本与团队网关同时要用 |
配置写在哪：同一份文件的两层
Codex 的 MCP 配置与主配置同住一个 config.toml，位置分两层：全局层在用户主目录的 ~/.codex 下，写在这里对所有项目生效；项目层在项目目录内，只对这个项目生效，两层怎么合并、优先级谁高，config.toml 分层一篇拆过，这里不重复。MCP 条目挂在 mcp_servers 段下，每个服务一条：stdio 服务写启动命令与参数，HTTP 服务写 URL 与认证信息。新手最常见的问题是条目写错了层——想全局生效的写进了项目层，换个目录就「服务消失了」；或者段名拼错，整个条目静默失效。还有一点与普通参数不同：改完 MCP 配置要重启会话才加载，当前会话不会热更新。
装完先验证：两个检查入口
接上不等于能用，验证分两步走。第一步在命令行跑 codex mcp list：列出当前加载的 MCP 服务与状态，条目缺失、服务起不来，在这里就能暴露——列表里没有你要的服务，回头查配置层与段名；列表里有但状态异常，问题在服务本身。第二步进会话输入 /mcp：查看运行时的连接情况与已注册的工具清单，这一步确认的是「真的连上了、工具真的递到了模型手里」。两步都对上，才谈得上调用。工具能用之后也别急着全量放开——一个服务往往挂着一整套工具，读写的、删改的都在里面，哪些该给 agent 开、哪些先关着，最小授权的配法见MCP 最小授权一篇；两步验证都过不去的情况，按顺序排查的清单见MCP 连不上一篇。
版本 pin 与共享配置的连带影响
还有两个细节值得单独说。一是版本 pin：MCP 服务实现本身在迭代，今天能用的工具，下个版本可能改了参数、换了名字，把服务版本固定下来——stdio 场景 pin 依赖的版本号，HTTP 场景与服务方约定接入的版本——行为才稳定可复现；服务端行为随版本怎么变，截至发稿版本，以官方更新日志为准。二是共享配置的连带影响：不少团队把 config.toml 放进仓库共享，MCP 条目跟着进了版本库——条目里的命令路径、URL、认证凭据会同步到每个同事的机器上，认证信息一旦入库就是泄露事故，凭据该放哪、怎么与配置分离，密钥别进仓库一篇专门讲。共享的是配置结构，不是你的凭据，这条线要在提交前分清。
MCP 接入速查
- 传输两选：本地工具走 stdio 子进程，远端服务走 HTTP
- 配置两层：全局 ~/.codex 对所有项目生效，项目层只对本项目
- 条目挂在 mcp_servers 段下，改完要重启会话才加载
- 验证两步：codex mcp list 看加载，/mcp 看连接与工具清单
- 版本 pin 固定服务行为，共享配置不共享凭据
关于 MCP 接入的常见疑问
- stdio 和 HTTP 以后会只剩一种吗？：两种传输面向的部署形态不同，本地进程与远端服务长期并存，协议本身把两者都作为一等公民支持。选型看工具在哪跑，不用赌哪种会被淘汰。
- 同一份 MCP 配置能给多个客户端共用吗？：MCP 是开放协议，服务端可以同时服务多个客户端，但各客户端的配置文件位置与字段写法并不一致，照搬另一家的配置前先对照本文档。另一个方向要小心：把一份配置复制到多个客户端后，改一处会同时影响所有端，动手前想想波及面。
- 为什么加了服务，会话里却看不到工具？：高频原因有三个：条目写错了层、段名或字段拼错、改完没重启会话。先跑 codex mcp list 反推——列表里没条目查配置，有条目连不上查服务进程与网络，排查细节见连不上那篇。
想把接入流程跑顺，可以让 DeepSeek 按你的工具清单生成 stdio 与 HTTP 两种条目的配置模板，再用豆包核对模板字段与官方文档的出入，最后在会话里用 /mcp 逐项确认工具已注册，一条链路走完就熟了。
