Codex 的 MCP 连接失败：区分启动、授权和工具调用

看到 MCP startup failed、handshaking failed 或工具调用超时，先记下是哪一个服务器或插件。MCP 用来连接工具和上下文，一个工具失败不一定意味着普通消息也无法使用。

🎯 这篇要完成：MCP 连接失败。 定位失败的那一层。

原创流程示意，帮助记住顺序；具体按钮、字段和条件以当前页面与本次订单为准。

一、确认来源和失败阶段

服务器可能来自你自己写的配置，也可能由已安装插件提供。先查看工具名称、完整错误、客户端版本，以及失败发生在启动还是第一次调用时。

桌面应用按当前版本进入 Settings → MCP servers 查看；CLI 可以运行：

codex mcp list
codex mcp --help

前者查看已配置服务器，后者看当前版本支持的命令。在 CLI 会话内，/mcp 可查看工具；列表里存在名字，还不能证明实际调用成功。

本地工具先按该项目的安装说明确认运行环境，不要直接运行来源不明的“修复脚本”。远程 MCP 地址是协议接口，普通首页或官网登录页不能随意替代。

官方说明同一 Codex host 的桌面应用、CLI 与扩展可共享 MCP 配置；但不同电脑、WSL 或自定义主目录要核对实际使用的配置，不能假定都读取了同一个文件。

支持 OAuth 的 Streamable HTTP 服务器，可按官方说明运行 codex mcp login <服务器名称>，名称替换为配置里真实的那一项。只有该服务器支持这条认证路径时才使用。

使用 Bearer Token 或环境变量的工具，按服务说明确认变量与权限，不把令牌打印到聊天里。授权成功仍可能因外部账号没有某个文件的访问权而失败，需要继续核对外部服务权限。

插件工具还可能受工作区管理员控制。个人重新安装，不一定能改变单位禁用的功能；这种情况保留错误并找管理员确认。

官方配置区分 startup_timeout_sec 和 tool_timeout_sec：前者等服务器初始化，后者等某次工具执行。当前文档默认分别为 10 秒与 60 秒，但插件和自定义配置可能不同。

只有已确认服务能正常工作、只是启动较慢时，才考虑按实际情况调整启动等待。握手格式错误、地址写错或授权失败，延长时间通常不能修好原因。

自建的非必需服务器，可以备份配置后用 enabled=false 暂停，不必删除整份配置。设置了 required=true 的已启用服务器若初始化失败，可能阻止整体启动；单位要求的工具先找管理员。

先确认基础对话可用，再调用原来失败的工具做一个小的只读操作，例如查一个测试文件或读取一段允许访问的文档。检查实际返回结果，不能只看状态文字。

若还失败，将工具名、来源、版本、失败阶段和脱敏错误交给AI 排错指南。返回 HTML / DOCTYPE 时看响应排查，文件或网络被权限挡住时看权限说明。

本地进程没启动，要看启动命令、工作目录和依赖；远程服务没有完成授权，要看当前支持的登录流程；已经列出工具但某次调用失败，要看工具输入、权限与服务返回。

不要把三层日志一起交给陌生工具“自动修复”，其中可能包含密钥或访问令牌。先摘取有关的脱敏错误、连接类型和发生步骤。

如果最近改过命令、环境变量或认证方式，保留原有效配置作为对照。只调整有依据的一项，验证是否改变了原错误，再继续下一项。

最后以实际的小范围工具调用完成为标准，不能只凭列表中出现了工具名称就认定整个流程正常。

💡 小锅提醒：连上工具，不等于调用成功。