# Claude Code MCP 连接失败怎么办？按配置、授权、工具调用逐层排查

原文：https://itjc.com/tutorials/claude-code-mcp-troubleshooting/
主题：MCP；级别：进阶；更新时间：2026-11-15。

> 区分配置已保存、连接成功和任务可完成，提供只读排查命令、故障记录模板及 HTTP/stdio 的检查顺序。

## 先分清你卡在哪一层
添加配置成功、服务连接成功、工具能完成目标任务，是三种不同结果。先找出失败的层次，再改一项配置。本文参考当前官方文档整理排查流程，没有连接你的私有服务，也没有把示意报错当作实测截图。

准备可用的 Claude Code、一个你有权使用的 MCP 服务，以及该服务当前安装说明。不要从搜索片段猜测地址、凭据或启动参数。

## 第一步：收集最小故障记录
在实际使用 Claude Code 的同一项目目录执行只读检查。把 SERVER_NAME 替换为自己的服务名；不要连同尖括号输入。

```sh
claude --version
claude mcp list
claude mcp get SERVER_NAME
```

进入 Claude Code 交互会话后，用 /mcp 查看服务面板。保存服务名、连接类型、当前项目、版本、时间与错误原文。分享记录前移除令牌、私有路径和敏感主机信息。

```text
工具及版本：
项目目录（可脱敏）：
服务名 / HTTP 或 stdio：
配置是否存在：
连接状态与错误原文：
最后一次成功时间：
最近修改：
本轮只改变的一个因素：
```

## 第二步：配置看不见时先查目录与作用域
如果列表里根本没有服务，先确认执行命令的项目和安装时一致，再核对配置作用域。不要立即重装整个 Claude Code。如果存在同名但地址不同的配置，先记录两处定义，由项目负责人确认应使用哪个端点。

若显示 Pending approval，表示项目服务仍需审阅批准。先核对仓库与服务来源，在交互会话处理对应信任流程；不要为省一步而全局放开未知仓库或服务。

## 第三步：HTTP 服务分开检查地址和授权
地址应是服务文档给出的 MCP 端点，不一定等于官网首页。浏览器能打开首页，不代表 MCP 路径存在。常见排查方向如下；HTTP 状态只是线索，最终以服务端日志与文档为准。

- 404：核对主机、路径和服务版本，检查是否误用了介绍页。
- 401：核对当前登录、凭据有效期和所需授权流程。
- 403：核对账户权限、资源访问范围或组织策略。
- 超时：检查当前机器的网络、代理与服务是否可达，记录发生时间。

不要把令牌粘到聊天里证明自己登录了，也不要关闭 TLS 校验掩盖证书问题。对于 OAuth 服务，在官方支持的登录流程中恢复授权，再重复同一个小查询。

## 第四步：stdio 服务检查启动环境
stdio 服务在本机启动进程。终端能运行而另一个入口失败，优先比较运行用户、工作目录、可执行文件路径、环境变量是否存在。只记录变量名，不输出完整值。

按服务官方说明在相同账户下运行启动命令，查看是否缺少运行时、依赖或参数。如果服务启动后立刻退出，保留退出码和错误日志。不要把另一款客户端的 JSON 配置不经核对就原样搬来。

## 第五步：连接成功后做一次只读验收
选择服务支持的最小只读任务。例如文档服务查询“指定产品的官方入门页面”，要求返回标题、链接与对应段落。先不要测试删库、发消息或创建付费资源。

如果连接正常但工具调用失败，进一步区分：工具未提供、资源未授权、参数不符合要求、返回内容不足以回答。换一个没有权限的资源反复重试，通常不能解决权限问题。每次只换一个条件，让结果可比较。

## 什么时候可以结束排查
- 当前项目能看到正确服务，地址与预期一致。
- 状态正常，最小只读任务返回可核对结果。
- 记录了根因、修改项和验证方式，而不只是“重启好了”。
- 未为修复一个服务而扩大其他系统的权限。

如果仍失败，把脱敏后的故障卡、错误原文和最近变更交给服务维护者。下一步可读 [MCP 基础](/tutorials/mcp-explained/) 与 [连接官方文档服务](/tutorials/connect-docs-mcp/)，不要同时新增多个服务来碰运气。

## 官方资料与参考

- [Claude Code 官方 MCP 文档](https://code.claude.com/docs/en/mcp)
- [Claude Code 官方故障排查](https://code.claude.com/docs/en/troubleshooting)
