直接答案
MCP 故障应脱离主任务按配置、进程、传输、协议和业务工具五层验证；工具未显示不等于模型故障。
这篇内容解决什么问题
解决 Codex 与 Claude Code 中 MCP Server 启动失败、连接断开、认证失败和 tools not showing。
先确认症状与影响范围
客户端显示 MCP Server 启动失败、连接断开、初始化超时或工具列表为空。stdio 服务可能在启动后立即退出；HTTP 服务可能返回 DNS、TLS、401 或协议错误。
MCP 配置存在不代表能力贯通。必须依次确认进程可运行、传输可达、初始化握手成功、工具列表返回以及最小只读调用可执行。
- 确认服务名、配置作用域、传输类型和启动参数。
- 确认 stdio 的 stdout 没有混入普通日志，HTTP URL 使用正确 MCP 端点。
- 确认凭据、协议版本和客户端权限允许列出工具。
常见原因与责任边界
MCP 同时涉及本地进程或远程服务、JSON-RPC 协议和客户端权限。只反复重启 Codex 或 Claude Code无法修复服务命令、URL 或认证本身。
- stdio 可执行文件不在 PATH、参数错误、依赖缺失或进程立即退出。
- 普通日志写入 stdout，破坏 JSON-RPC 消息流。
- HTTP URL、TLS、OAuth/bearer token 或组织 allowlist 不正确。
- 初始化成功但工具 schema 无效、工具被权限规则拒绝或上下文未刷新。
按层执行最小诊断
先使用客户端的 list/get 查看最终配置。stdio 服务在同一用户和工作目录下独立运行 --help 或健康检查；HTTP 服务先检查 DNS、TLS 和认证，再查看 MCP 状态。
每次只改一层。禁用一个故障 MCP 可以验证它是否影响客户端启动，但删除配置不会自动撤销远程 token。
- 01配置层确认服务名、作用域、命令/URL、参数与环境变量名称。
- 02进程与网络层stdio 独立启动；HTTP 检查 DNS、TLS、状态码和超时。
- 03协议层确认 initialize、版本协商和 tools/list 成功。
- 04业务层调用一个无副作用的只读工具并审查结果。
codex mcp list --json 2>/dev/null || true
codex doctor --summary 2>/dev/null || true
claude mcp list 2>/dev/null || true
# 再分别使用 codex mcp get <name> 或 claude mcp get <name>。
# stdio 服务只运行可信命令的 --help，不执行来源不明的安装管道。
针对根因完成修复
按根因修正可执行路径、参数、stdout 日志、HTTP URL 或认证。配置恢复后重新启动客户端，让工具清单刷新，并从一个只读工具开始验证。
- 01修复启动条件固定可信版本，确保命令、工作目录、PATH 与依赖正确。
- 02分离日志stdio 服务只在 stdout 输出协议消息，普通日志写 stderr。
- 03修复远程连接对齐 URL、TLS、OAuth/bearer 与组织访问策略。
- 04最小授权重新加载后先允许一个只读工具，再逐步开放。
1. client list/get 能读取最终配置
2. server process 或 HTTP endpoint 可达
3. initialize 与 tools/list 成功
4. 一个只读工具返回预期结构
5. 日志无 token、项目秘密和协议污染验证修复而不是只看一次成功
验收至少覆盖重启后的配置持久性、工具发现和一次最小只读调用。若服务拥有写权限，还要确认未经授权的写动作仍会被拒绝或请求人工审批。
- 客户端重启后服务状态正常，工具列表稳定可见。
- 最小只读工具结果可验证，超时和错误可观测。
- 移除或禁用服务后，远程 token 按需另行撤销。
安全边界与升级证据
本地 MCP 命令等同运行本机程序。不要直接执行来源不明的 npx、curl 管道或二进制；项目级配置可共享地址和参数，但不共享个人凭据。
- 固定来源与版本，先在受限环境测试。
- 凭据通过 Secret、环境变量名或 OAuth 提供。
- 外部工具结果视为不可信输入，写操作保留审批。
官方来源与核验范围
本文以协议规范和客户端官方文档为事实依据。错误文案、重试头和配置字段可能随服务或客户端版本变化；执行前请核对来源，并对日志与请求样例脱敏。
查看技术核验方法