先分清你卡在哪一层
添加配置成功、服务连接成功、工具能完成目标任务,是三种不同结果。先找出失败的层次,再改一项配置。本文参考当前官方文档整理排查流程,没有连接你的私有服务,也没有把示意报错当作实测截图。
准备可用的 Claude Code、一个你有权使用的 MCP 服务,以及该服务当前安装说明。不要从搜索片段猜测地址、凭据或启动参数。
第一步:收集最小故障记录
在实际使用 Claude Code 的同一项目目录执行只读检查。把 SERVER_NAME 替换为自己的服务名;不要连同尖括号输入。
claude --version
claude mcp list
claude mcp get SERVER_NAME进入 Claude Code 交互会话后,用 /mcp 查看服务面板。保存服务名、连接类型、当前项目、版本、时间与错误原文。分享记录前移除令牌、私有路径和敏感主机信息。
工具及版本:
项目目录(可脱敏):
服务名 / HTTP 或 stdio:
配置是否存在:
连接状态与错误原文:
最后一次成功时间:
最近修改:
本轮只改变的一个因素:第二步:配置看不见时先查目录与作用域
如果列表里根本没有服务,先确认执行命令的项目和安装时一致,再核对配置作用域。不要立即重装整个 Claude Code。如果存在同名但地址不同的配置,先记录两处定义,由项目负责人确认应使用哪个端点。
若显示 Pending approval,表示项目服务仍需审阅批准。先核对仓库与服务来源,在交互会话处理对应信任流程;不要为省一步而全局放开未知仓库或服务。
第三步:HTTP 服务分开检查地址和授权
地址应是服务文档给出的 MCP 端点,不一定等于官网首页。浏览器能打开首页,不代表 MCP 路径存在。常见排查方向如下;HTTP 状态只是线索,最终以服务端日志与文档为准。
- 404:核对主机、路径和服务版本,检查是否误用了介绍页。
- 401:核对当前登录、凭据有效期和所需授权流程。
- 403:核对账户权限、资源访问范围或组织策略。
- 超时:检查当前机器的网络、代理与服务是否可达,记录发生时间。
不要把令牌粘到聊天里证明自己登录了,也不要关闭 TLS 校验掩盖证书问题。对于 OAuth 服务,在官方支持的登录流程中恢复授权,再重复同一个小查询。
第四步:stdio 服务检查启动环境
stdio 服务在本机启动进程。终端能运行而另一个入口失败,优先比较运行用户、工作目录、可执行文件路径、环境变量是否存在。只记录变量名,不输出完整值。
按服务官方说明在相同账户下运行启动命令,查看是否缺少运行时、依赖或参数。如果服务启动后立刻退出,保留退出码和错误日志。不要把另一款客户端的 JSON 配置不经核对就原样搬来。
第五步:连接成功后做一次只读验收
选择服务支持的最小只读任务。例如文档服务查询“指定产品的官方入门页面”,要求返回标题、链接与对应段落。先不要测试删库、发消息或创建付费资源。
如果连接正常但工具调用失败,进一步区分:工具未提供、资源未授权、参数不符合要求、返回内容不足以回答。换一个没有权限的资源反复重试,通常不能解决权限问题。每次只换一个条件,让结果可比较。
什么时候可以结束排查
- 当前项目能看到正确服务,地址与预期一致。
- 状态正常,最小只读任务返回可核对结果。
- 记录了根因、修改项和验证方式,而不只是“重启好了”。
- 未为修复一个服务而扩大其他系统的权限。
如果仍失败,把脱敏后的故障卡、错误原文和最近变更交给服务维护者。下一步可读 MCP 基础 与 连接官方文档服务,不要同时新增多个服务来碰运气。