“MCP 工具没有出现”几乎是新手最常见的问题，但它其实不是一个单独故障，而是一组不同层级问题的共同表现。服务没有被正确添加、连接没有建立、认证没完成、项目审批没通过、服务器只暴露资源没暴露工具、工具描述不合规，都会让你最终看到同一个结果：界面里什么都没有。所以排查时最怕一上来就重装客户端或改提示词，最有效的方法反而是按层逐步缩小范围。
第一层：先确认服务到底有没有被登记
对 Codex 来说，先看 `codex mcp list` 或对应界面；对 Claude Code 来说，先看 `claude mcp list`。如果服务名根本不在列表里，问题一定还在配置层，而不是工具层。此时要检查的包括：配置文件路径写对没有、命令是否真的执行过、项目级配置是否放到了受支持的位置、名称是否冲突、配置语法是否被客户端接受。
第二层：连接建立了没有
能看到服务名，不代表连接成功。你要继续确认客户端是否已经和服务器完成初始化。如果是本地 stdio，要看命令能否启动、依赖是否齐全、当前目录是否正确、环境变量是否可读；如果是远程 HTTP，要看 URL 是否正确、网络是否可达、证书或代理是否拦截了连接。有些服务在列表里存在，但实际上每次会话启动都失败，于是工具也不会显示。
第三层：认证和授权是否完成
很多远程服务支持 OAuth 或 Bearer Token。配置写完后，如果认证尚未完成，客户端往往不会拿到完整能力。Codex 官方文档提到，OAuth 服务需要在列表中完成 Authenticate；Claude Code 文档则提醒项目级服务可能停在 `Pending approval`，需要你在交互式会话中批准。也就是说，“已经配置”与“已经可用”之间，常常还隔着一层授权动作。
第四层：服务器到底暴露了什么能力
即使连接和认证都没问题，工具仍然可能为空。原因很简单：服务器也许只暴露了资源或提示模板，没有暴露工具；或者它把某些工具按角色、范围、目录、账号权限做了过滤。很多人以为任何 MCP 服务都该自动出现一长串工具，这种预期本身就不一定成立。排查时要回头看服务文档，确认它究竟承诺提供什么。
第五层：工具描述是否能被客户端识别
工具不是只要后端存在就行。客户端通常还需要拿到清晰的名称、用途说明、参数结构和可解析返回。如果服务端工具定义不规范，客户端可能直接忽略，或者虽然显示出来却无法调用。MCP 调试文档和 Inspector 的价值就在这里：你可以更直观看到服务究竟返回了哪些能力，以及这些能力的描述是否完整。
一套实用排查顺序
- 看配置是否生效：服务是否出现在列表里。
- 看连接是否建立：本地命令能否启动，远程地址能否访问。
- 看授权是否完成：是否需要 OAuth、是否仍在 Pending approval。
- 看能力是否存在：服务是否真的暴露了工具。
- 看工具定义是否规范：能否被客户端正常发现和解析。
- 最后再做最小调用测试，而不是直接执行复杂写操作。
Inspector 和调试工具什么时候最好用
当你已经确认客户端配置没问题，但还是无法判断到底是服务器没返回工具，还是客户端没正确显示时，官方提供的 MCP Inspector 和调试文档就很有价值。它们适合做“能力层”的核对，而不是替代最基础的配置检查。很多人一开始就上 Inspector，其实效率不高；等你排除掉配置、连接、认证这三层后再用，定位会快得多。
最常见的五种真实原因
- 服务类型写错，把 HTTP 服务当成 stdio，或把 JSON 配置中的 `type` 漏掉。
- 环境变量或请求头没传入，导致认证失败但服务名仍然存在。
- 项目级服务尚未批准，尤其是 Claude Code 的 `Pending approval`。
- 服务只提供资源不提供工具，用户预期和实际能力不一致。
- 工具定义不完整，客户端直接过滤掉。
避免重复踩坑的做法
最稳的方式是给每个新服务建立一个“只读验证脚本”：先列出工具，再调用一个无副作用工具，最后记录认证方式、配置文件位置和最小可用命令。这样下一次换机器、换项目、换客户端时，你就不用重新从零猜起。
相关阅读
总结
MCP 工具没有出现，通常不是“模型不行”，而是配置、连接、认证、能力发现和工具定义中的某一层没有打通。按层排查，比反复重装或盲改参数更有效，也更适合你后面维护多套服务。
