给 Codex 配好一个 MCP 服务，会话里却看不到工具；或者时好时坏，重启几次才连上——AI agent 的 MCP 故障大多卡在接入链路的三处：配置没被读到、服务进程没起来、认证没通过。乱试配置是排查的大忌，改十处不如按顺序查三处。这篇给一份能直接照做的三步排查清单：每一步查什么、用什么命令、结果怎么解读，再补上两个超时参数的显式配法；接入配置本身怎么写，见Codex 接 MCP一篇打底。
先分清两层：没加载与没连上
排查前先建立一个分层意识：「配置没加载」与「服务没连上」是两个层面的问题，症状都是会话里没有工具，根因却完全不同。配置没加载：条目写错了层（全局还是项目）、段名拼错、改完没重启会话，服务压根没进入加载队列。服务没连上：配置读到了，但进程启动失败、连不上端口或认证被拒。分层的判据就是第一步的输出——列表里有没有条目。没有条目，问题全在配置侧，去查写法与层级，config.toml 分层的合并规则见config.toml 分层一篇；有条目但状态异常，才进入后面的服务侧排查。
| 看到的信号 | 指向哪一处 | 下一步查什么 |
|---|---|---|
| codex mcp list 里没有条目 | 配置层：层级、段名、是否重启 | 核对全局层与项目层写法，重启会话再列一次 |
| 有条目但状态异常 | 服务进程本身 | 把启动命令拿到终端裸跑，看能不能在前台等待输入 |
| 裸跑能通，进了 Codex 连不上 | 子进程继承的环境变量不一致 | 把缺的变量补进服务条目的 env 配置 |
| 时好时坏、重启几次才连上 | 启动时长贴着默认等待 | 显式调大 startup_timeout，不靠默认值 |
三步排查：条目、裸跑、环境与认证
第一步，打印条目：命令行跑 codex mcp list，确认服务在列表里、看状态列。列表为空或缺条目，回到配置层查——这是三步里返回率最高的一步，多数「连不上」其实死在这一步。
第二步，裸跑命令：把 stdio 服务的启动命令原样拿到终端里单独执行，不经过 Codex。能正常启动并在前台等待输入，说明命令本身没问题；终端报 spawn ENOENT，说明可执行文件找不到——命令拼错、依赖没装、路径不在环境里，都在这一步现形。HTTP 服务对应的做法是用 curl 或浏览器直接访问健康检查端点，服务本身通不通先单独确认。
第三步，查环境变量与认证：同一台机器、同一份配置，裸跑能通、进了 Codex 却连不上，差别通常在运行环境——Codex 启动的子进程继承的环境变量与你终端里的不一定一致，依赖某些变量才跑得起来的服务会在这里断掉，缺的变量补进服务条目的 env 配置里。HTTP 服务的认证是另一处高发点：返回 401 就是凭据问题，token 过期、scope 不对、OAuth 流程没走完都算，重新走一遍授权流程，确认凭据写在正确的字段里。
两个超时参数：别让慢服务被误判
有一类「连不上」其实是「连得慢」。MCP 服务启动要时间：拉起运行环境、加载依赖、建立连接，重的服务十几秒起步；如果启动超过默认等待时长，Codex 会把它当作启动失败处理，症状与真连不上一样。这类情况用 startup_timeout 显式把启动等待调长，先让服务能进场。进场之后还有第二道：工具调用本身的耗时——查询大表、抓取长网页的工具一跑几十秒，超过调用等待时长同样会被判失败，tool_timeout 管这一段，按最慢工具的实际耗时配置。两个参数都写进服务条目里显式声明，不要依赖默认值；参数之外，重试与超时在 agent 工具链里的整体机制，见工具重试一篇。
排查之后：把结论固化下来
查完不要只停留在「这次能用了」。三个固化动作值得做：一是把排查结论写进项目的 AGENTS.md——哪些服务依赖哪些环境变量、启动慢属于正常现象，避免下一个人重新踩一遍，AGENTS.md 的写法见AGENTS.md 写法一篇；二是固定服务版本，服务升级改了行为又「连不上」时，先怀疑版本再排查配置，pin 版本的道理见接入篇；三是给服务配好两个超时参数再交给团队用，连得上且稳得住，才算接入完成。连上之后还有一层常被忽略的事：工具全量放开并不安全，最小授权的配法见MCP 最小授权一篇。
MCP 排查速查
- 先分层：list 没条目查配置层，有条目异常查服务侧
- 三步顺序：打印条目 → 裸跑命令 → 查 env 与认证
- spawn ENOENT 是命令找不到，401 是凭据问题
- 慢服务配 startup_timeout 与 tool_timeout，别靠默认值
- 结论固化进 AGENTS.md 与版本 pin，团队不重踩
关于 MCP 排查的常见疑问
- 时好时坏、重启几次才连上，算哪一类？：大概率是启动时长贴着默认等待的边——机器负载高时启动变慢，超过等待时长就判失败。把 startup_timeout 显式调长即可，属于超时问题，不用动配置结构。
- 裸跑命令能通，Codex 里就是不行，先查什么？：先查环境差异。终端里手工 export 过的变量、激活过的虚拟环境，Codex 启动的子进程都没有；把必需的变量写进服务条目的 env 配置，把命令写成可执行文件的完整路径，差异就消掉了。
- HTTP 服务返回 401，token 明明刚刷新过？：确认三处：凭据是否写在服务条目的正确字段里而不是环境变量旧值、OAuth 流程是否完整走完而不是只拿了 code、服务端要求的 scope 与凭据实际 granted 的范围是否一致。三处都对再考虑服务端的问题。
排查时想让 AI 帮忙提速，可以把 codex mcp list 的输出和裸跑命令的报错一起丢给 Kimi，让它按三步清单定位卡在哪一层；豆包适合帮你把排查结论整理成 AGENTS.md 的条目，团队下次照着查就行。
