浏览 AI 知识库
MCP 连接失败怎么排查：检查进程、配置、认证、网络和权限
MCP 连接失败时，依次固定进程、配置、认证、网络和权限中的一层。每次只改变一个条件并保存日志，偶尔连上才不会掩盖真正原因。
沿完整工作流推进
前一阶段的可检查结果，是下一阶段的输入；中间证据不足时停在当前阶段。
反复重装以后偶尔连上了，仍然不能说明故障已经解决
MCP 连接失败后用户反复重装包，配置、认证、网络和权限同时改变。最后偶尔连上，也没有证据说明问题在哪。
- 失败层级与证据对应
- 唯一改动可复现
- 工具发现和真实调用都复测
先确认这次任务的起点、边界和交付
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | 客户端显示 disconnected；Server 单独启动正常；stderr 有 `handshake timeout`；使用本地代理。 |
| 不能越过的边界 | 按进程、配置加载、握手、认证、网络、工具发现与调用逐层；每次只改一个条件并保留日志。 |
| 要交付的结果 | 分层诊断报告 |
从“进程或服务”走到“调用与资源权限”
| 当前阶段 | 实际处理 |
|---|---|
| 进程或服务 | 本地命令是否启动、退出码和 stderr；远程端点是否解析、连通和返回预期协议。 |
| 配置 | 文件位置、语法、作用域、命令路径、参数和环境变量是否被当前客户端实际读取。 |
| 认证 | Token 类型、过期、OAuth 回调、scope、用户和组织是否匹配目标资源。 |
| 工具发现 | 连接成功后是否列出能力，Server 是否声明工具，客户端是否支持并授权。 |
| 调用与资源权限 | 使用最小参数调用，关联客户端与 Server 日志，确认失败来自工具、网络还是资源本身。 |
工具列表为空时，按证据顺序排除五层原因
| 层级 | 观察到的现象 | 记录的证据 | 下一步 |
|---|---|---|---|
| 进程 | 本地 Server 启动后立即退出 | stderr：找不到启动命令，退出码 127 | 确认命令路径和运行时，不先改权限 |
| 配置 | 命令在终端可运行，Client 看不到 | Client 实际读取的配置路径与编辑路径不同 | 修正作用域后重新列工具 |
| 认证 | 远程端点返回 401 | Token 已过期，scope 不含目标资源 | 按官方流程续期并用最小权限复测 |
| 发现 | 连接成功但工具列表为空 | Server 日志未声明工具或客户端版本不支持 | 核对 Server 能力声明和客户端版本 |
| 资源 | 工具可见但读取目录被拒绝 | 资源路径不在允许根目录 | 调整测试目录或授权，不扩大生产范围 |
每次只推进一层并保留原始错误；重新安装后恢复，不等于已经找到根因。
完成后的分层诊断报告
诊断表确认进程与配置正常，关闭代理后握手成功，问题定位到代理拦截本地连接；恢复代理并加正确 bypass 后工具列表和只读调用都通过。没有重装 Server。
为什么“连接恢复一会儿又断”还不能交付
连接恢复一会儿又断
- 原因
- 只验证了启动，没有观察生命周期和超时
- 怎么改
- 保留连续日志与时间线，检查进程退出、心跳、代理和资源限制