Codex MCP 连接失败或超时？从启动、认证到工具调用逐步排查

已经配置了 MCP，Codex 却报 connection failed、启动超时，或者能列出服务器却调用不了工具。配置存在、服务器进程启动、初始化与认证通过、工具真正执行成功，是不同的检查点。 先找出失败阶段，再决定修改哪一项。

本文处理 Codex 作为客户端连接外部 MCP 服务器的情况，包括 codex mcp connection failed、codex mcp server not starting 与 codex mcp timeout；不涉及把 Codex 自身作为服务器暴露的接口迁移。

先按错误现象分流

现象	优先检查	通过这一层的证据
配置列表没有目标服务器	实际配置文件、执行主机、启用状态与项目加载	当前环境能读取目标条目
`command not found`、找不到程序或进程马上退出	STDIO 的命令、参数、运行时、工作目录与环境	目标进程能按预期启动并接受协议通信
初始化或启动超时	启动耗时、协议输出、HTTP 端点与认证	客户端初始化成功并取得工具清单
`401` 或 OAuth 登录失败	该 MCP 的凭据、授权与回调	对应服务器认证成功并能初始化
工具可见，调用时报错或超时	工具参数、独立权限、上游服务与调用耗时	一次可控的只读工具返回预期数据

记录完整错误和发生时间，区分“连接时失败”与“调用某个工具时失败”。不要先删除全部配置、清除所有凭据或把超时统一改成很大的值。

1. 先确认当前 Codex 能发现这份配置

适用情况： 已经编辑文件，但当前客户端里没有目标 MCP，或者只在另一个环境能用。

在与任务相同的主机、用户和项目目录中运行：

codex --version
codex mcp --help
codex mcp list
codex mcp get your-server

将 your-server 替换为已有条目的实际名称；若当前版本没有某个子命令，按其 --help 与匹配版本的官方文档操作。get 会显示配置细节，输出可能含端点或凭据，不把完整结果贴到公开求助中。

官方本地配置入口是用户 config.toml，默认 ~/.codex/config.toml，也支持受信项目中的 .codex/config.toml。使用 CODEX_HOME 时先确认实际目录。VS Code 自身的 .vscode/mcp.json 不是 Codex 的同一份配置；编辑器内其他扩展能用，也不证明 Codex 已加载。

预期结果： 列表能找到目标，get 中的传输方式、命令或 URL 正确，且没有被 enabled = false 禁用。这只证明配置被读取，不能证明连接成功。找不到时继续看 config.toml 不生效排查，不重复添加同名条目。

同一 Codex 主机上的桌面应用、CLI 与 IDE 扩展可共享 MCP 配置；本机、WSL、容器及远程执行环境仍需分别核对。任务切到另一 worktree 后才出问题时，先确认项目路径与环境，参考 worktree 改动与实际目录定位。

2. 看当前会话状态，不只看配置列表

在 CLI 的会话输入框使用 /mcp 查看活动服务器和可用工具，不是在系统 shell 里输入。桌面应用可在 Settings → MCP servers 检查对应条目；IDE 扩展可从齿轮菜单进入 MCP servers。

操作： 记录目标服务器是否活动、是否要求认证、是否出现本次预期工具。修改桌面条目后按界面的 Restart，IDE 按 Restart extension；CLI 用新会话重新检查，避免把旧会话状态当作新配置结果。

判断下一步：

服务器未活动或启动失败：按传输方式进入下一节。
显示要求认证：核对第 4 节的 MCP 独立认证。
已活动但少工具：检查 enabled_tools、disabled_tools 与服务器实际暴露的工具；允许列表和禁用列表可能影响可见范围。
工具已经可见：直接进入第 6 节做实际调用验证。

工具是否被模型选中与工具能否执行也不同。只回答“我可以使用这个工具”不是连接或调用证明。

3. STDIO：先查程序能否在 Codex 的环境中启动

适用情况： 服务器配置使用 command 与 args，由客户端启动本地进程。

检查实际可执行文件、参数和服务工作目录。macOS/Linux 用 command -v node、command -v npx；PowerShell 用 Get-Command node、Get-Command npx。使用其他运行时就替换程序名。查询要在服务真正运行的主机上进行。

下面是结构示例，仅适用于已安装并确认可信的本地服务，不是可以原样运行的服务器地址：

[mcp_servers.local_docs]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/server.js"]
cwd = "/absolute/path/to/server-project"
env_vars = ["DOCS_TOKEN"]

把路径和变量名换成该服务器文档要求的实际值。Windows 同样要使用服务所在环境可执行的路径；TOML 中可用单引号字面量表示反斜杠路径，例如 command = 'C:\Program Files\nodejs\node.exe'，不要把 WSL 路径填给 Windows 原生进程。

逐项验证：

命令和参数： 在匹配的工作目录与环境中，按服务官方启动方式运行已审阅的命令。找不到程序时先修复对应运行时或路径；不要默认提权或全局重装所有依赖。
工作目录： 服务依赖相对路径时确认 cwd。终端从项目目录运行成功，而应用从其他位置启动失败，可能是相对路径差异。
环境变量： 用只显示“已设置／未设置”的方式核对服务所需变量，不输出值。桌面应用启动时继承的环境不一定等于刚打开的终端；按该服务要求配置允许转发的 env_vars 或适用环境来源，再重启客户端。
退出与协议： 记录退出码和必要的 stderr。服务一直等待 stdin 可能是正常状态；STDIO 通过 stdin/stdout 交换 JSON-RPC，普通调试日志应写 stderr，不能把启动横幅混进 stdout。

预期结果： 程序不因缺依赖、缺变量或路径错误退出，随后 Codex 能初始化并列出工具。手动运行只检查进程层；仍有握手、认证或工具错误时，继续排查，不能直接断定“手动能启动就是 Codex 的问题”。

4. HTTP：核对 MCP 端点，再处理独立认证

适用情况： 条目使用 url 连接远程 Streamable HTTP 服务。

使用服务器文档提供的完整 MCP 端点，包括必要路径。浏览器能打开服务首页，或对端点发普通 GET 得到 200，都不等于 MCP 初始化成功；404、405 也应结合请求方法和服务协议判断。

检查 DNS、代理、TLS 与服务端状态时，沿用该环境批准的网络配置。出现证书错误应核对证书链和企业 CA；不要关闭 TLS 校验。代理问题按客户端实际环境定位，不把取消代理当作通用修复。

按服务器支持的方式处理认证：

OAuth： 服务器支持 OAuth，且客户端显示需要登录时，CLI 可运行 codex mcp login your-server，或使用桌面/IDE 条目的 Authenticate。授权后重新检查连接。预注册客户端需按官方要求核对 client ID、声明的 scopes 与实际显示的回调 URL，不能照搬另一台机器的示例回调。
Bearer token： 若服务要求 token，可按服务器要求配置 bearer_token_env_var，并确认变量在实际连接环境中可用。变量名可以分享，token 值不能出现在命令截图、文章评论或 Git 中。
远程或无桌面环境： 先用 codex mcp login --help 查看当前版本支持的登录入口；某些版本提供 --no-browser，但是否能完成仍取决于服务授权和回调条件。不要笼统认定所有 headless 环境都支持或都不支持。

验证： 同一服务器不再报告认证错误，初始化后能看到预期工具。Codex 自己已经登录 ChatGPT，不代表外部 MCP 已获得授权；反过来，MCP 的 401 也不能只靠重登 Codex 账号解决。Codex 账号本身有问题时再看登录失败与 401 排查。

403 要核对对应服务返回的权限或 scope 原因，429 要检查限流和重试提示；它们不是统一的“密码错了”。登录成功但工具返回拒绝时，继续检查工具或资源级权限。

5. MCP timeout：先区分启动超时与工具调用超时

当前官方配置中，启动耗时对应 startup_timeout_sec，工具运行耗时对应 tool_timeout_sec，两项不能互相替代：

失败阶段	官方默认上限	修改前要有的证据
服务器启动与初始化	10 秒	启动链路正常，只是可测的准备耗时超过限制
服务器运行一次工具	60 秒	工具已被发现，调用确实启动，任务耗时可解释

只有确认是正常耗时超出限制，才在已有服务器表中调整对应项。例如，启动有确定的首次准备过程，且测得需要二十多秒，可尝试把该条目的 startup_timeout_sec 改为 30，其余条件保持一致，再重启验证。不要重复新建同名 TOML 表。

若是命令不存在、端点错误、认证被拒或进程崩溃，加长时间只会延迟失败。工具调用超时也不应通过修改启动超时处理；先检查工具参数、上游服务和服务端日志。

另有 mcp_optional_startup_grace_ms，控制初始工具目录等待可选服务器的时间，官方默认是 1000 毫秒；它与上述两项不同。只有确实在排查“工具目录生成时服务器尚未就绪”时才核对这一项；设为 0 表示等待各服务器的启动超时，并非永久取消所有超时。不要把这一时间窗口当成服务器已经断线的证据。

验证： 修改后，原来失败的那一阶段通过，并最终完成一次预期调用。仍在相同阶段报错时，保留准确错误，回到该阶段的路径、协议、认证或上游排查。

6. 用一次可控的只读调用验证整条链路

适用情况： 服务器已经活动，工具已出现，需要确认是否真正恢复。

选择你有权读取、内容已知且不含敏感信息的测试资源，按服务器的工具说明填写参数。在 Codex 会话中明确要求，例如：

请使用已连接的文档 MCP，只读取我指定的测试文档。
核对其中已知的标题与一条内容，说明实际调用了哪个工具及返回结果。
不创建、不修改、不删除数据，不调用其他服务代替。

先替换为自己的服务器名、实际工具和测试资源。观察可见的工具执行记录与返回内容，核对已知值；不要只接受模型自述。如果工具未被选用，明确指定工具再测，区分选择问题与调用错误。涉及模型回复或服务请求时，会使用相应的账号或服务额度。

如果调用超时，先到服务端确认动作是否仍在运行，尤其是原工具可能写入时，不盲目重试。只读小例子通过，而原任务失败，应继续定位原任务的参数、资源权限、上游依赖或耗时，而不是再次重装 MCP。

修复完成的判断与求助清单

依次确认：配置来自正确环境；目标服务器完成初始化和适用认证；预期工具可见；实际只读调用返回已知结果。每一层都保留可观察证据，失败就回到对应层。

仍失败时，只提供这些必要信息：客户端版本、主机与传输类型、脱敏的命令/参数或端点路径、错误阶段和时间、退出码或 HTTP 状态、相关超时值，以及最小复现步骤。隐藏 token、Authorization、Cookie、OAuth code 和工作资料，不上传完整配置或认证文件。

如果实际失败发生在 Skill 调用工具之前，继续看 Skills 不显示、不触发；普通依赖和命令错误可参考 Codex 常见故障排查。