问题现象

兴冲冲给 Claude Code 配好 MCP 服务器，结果一启动：

MCP error -32000: Connection closed

或者进入会话后发现该 MCP 服务器状态是 failed，它提供的工具一个都用不了。

配置照着文档抄的，怎么就是连不上？

原因分析

-32000: Connection closed 的含义很直接：Claude Code 尝试把 MCP 服务器作为子进程拉起来，但这个进程启动后立刻退出了。问题基本都出在"拉起"这一环：

1. 启动命令本身跑不通——命令写错、可执行文件不在 PATH 里、Windows 下 npx 需要特殊写法
2. node 环境混乱——nvm 多版本共存、node 路径冲突，导致子进程环境和你终端里的不一样
3. 服务器需要认证——没有完成 OAuth 授权，状态会是 needs-auth 而不是真正的故障
4. 服务器自身崩溃——依赖缺失、端口占用、版本不兼容

排查的核心手段就一个：把 Claude Code 干的事，自己手动干一遍——它拉不起来的命令，你在终端里跑一遍，报错就直接现形了。

解决步骤

第一步：/mcp看清状态

在 Claude Code 里输入：

查看每个 MCP 服务器的状态：connected 正常、failed 启动失败、needs-auth 待认证、pending 还在连接中。先确认你的服务器挂在哪一档，再对症处理。

第二步：手动跑一遍启动命令（最关键）

打开你的 MCP 配置（项目级在 .mcp.json，用户级在 ~/.claude.json），找到该服务器的 command 和 args，原样拼起来在终端里手动执行：

• 命令报"找不到命令"→ PATH 问题，进入第三步
• 命令直接报模块/依赖错误 → 服务器本身的问题，去该项目的仓库看 issue
• 命令正常挂起等待输入 → 命令没问题，检查 Claude Code 侧的配置拼写

第三步：Windows 用户检查命令写法

Windows 下 npx 不是真正的可执行文件，通过 CMD 间接启动更稳。把配置里的 command 改成：

这是 Windows 原生环境（非 WSL）下 MCP 连接失败的头号原因。

第四步：检查 node 环境

三个命令都要能正常输出版本。如果机器上装过多个 node（nvm、单独安装混用），路径可能互相打架——社区里不少人彻底卸载多余的 node 发行版、只保留一套之后，MCP 立刻就能连上了。

第五步：需要认证的服务器完成授权

/mcp 里状态是 needs-auth 的，按界面提示完成 OAuth 授权流程即可，这不是故障。

第六步：还不行？瘦身启动排除干扰

用安全模式启动，排除是不是 hook、其他扩展或配置干扰导致：

此模式会停用自定义配置。如果安全模式下 MCP 能连上，说明问题出在你的某项自定义配置上，逐项恢复即可定位。

验证是否修复

修完配置后重启 Claude Code，再执行 /mcp，目标服务器状态变为 connected、它的工具可以正常调用，即已修复。

常见问题

Q：.mcp.json 和全局配置有什么区别？

.mcp.json 放在项目根目录，只对该项目生效，适合团队共享（记得提交进 git）；用户级配置全局生效，适合放个人通用的服务器。排查时先确认你改的是生效的那一份。

Q：为什么报错信息一闪而过，什么都看不到？

因为服务器进程是后台子进程，崩了只剩一行结论。所以才有第二步——手动在终端里跑启动命令，报错信息就完整暴露出来了。

Q：连接成功过，后来突然变 failed？

多为环境变化：node 升级/切换版本、npm 全局包被清理、或者服务器新版本有 bug。重新走一遍第二步的手动执行，基本都能定位。

总结

MCP 排查就是一句话：Claude Code 只是替你执行了启动命令，连不上就把这条命令拿出来自己跑一遍。配合 /mcp 分清状态、Windows 下记得 cmd /c 前缀，九成的 -32000 都能自己解决。