Claude Code 的 MCP 服务器连接错误：按状态分类的成因与对策

你配置好了一个 MCP（Model Context Protocol）服务器，但打开 /mcp 时却看到它卡在这样的状态——是不是很眼熟？

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP 为 Claude Code 赋予了 “双手”——外部工具（文件操作、GitHub、数据库、各类 API），但 它的连接比你想象的更容易出问题。原因可分为三大类：“本地子进程启动失败”、“远程认证”、“配置文件错误”，而 /mcp 的状态显示会告诉你究竟属于哪一类。本文将基于官方信息，系统梳理 状态的读法、按原因分类的对策、Windows 特有的陷阱以及排查工作流。

先说要点。（1）先用 /mcp（以及 claude mcp list）查看状态——是 failed（启动失败）、needs authentication（认证）还是 pending approval（等待审批），对策完全不同。（2）本地（stdio）最常见的罪魁祸首是路径和环境变量，再加上 Windows 的 npx 问题。（3）远程（HTTP）最常见的罪魁祸首是 OAuth。（4）卡住时，运行 claude --debug mcp 查看服务器的错误输出（stderr）。不同版本的行为和默认值会有变化，请以最新官方文档为准核对。

1. 这个错误到底在告诉你什么

MCP 服务器大致分为 两种连接类型。（1）stdio（本地）——Claude Code 在你的机器上把服务器命令作为子进程启动，并通过标准输入输出通信。（2）HTTP（远程）——通过 URL 连接到云端服务器（旧的 SSE 已弃用）。“连不上”的具体含义，会因类型而大不相同。

本地（stdio）失败几乎总是“命令本身启动失败”——路径不对、npx 无法解析（尤其在 Windows 上），或因缺少必需的环境变量导致服务器立即崩溃。远程（HTTP）失败通常是“OAuth 尚未完成”——服务器返回 401/403 并显示 needs authentication。而当它 既不属于这两类、配置却又不生效时，就要怀疑 配置文件的位置、JSON 拼写错误或项目审批。

所以第一步是 “打开 /mcp，读取状态，判断它属于三大类中的哪一类。”把每个错误都当成笼统的“连不上”然后到处乱试，是绕远路。下一节讲解如何读取状态。

2. 先用 /mcp 读取状态

在会话中运行 /mcp（或在 shell 中运行 claude mcp list / claude mcp get <name>），可以看到每个服务器的状态。主要状态及其含义如下：

要点在于：“failed ＝启动问题，needs authentication ＝认证，pending ＝审批”——状态唯一地决定了你该怎么做。一个常被忽略的情况是 “已连接但工具为 0”——服务器启动了，却没有返回工具列表；此时应转向重新连接，或用 claude --debug mcp 查看日志。

3. 连接失败的主要原因与对策

下面列出 failed（本地启动失败）和配置问题的代表性原因，并配上对策。

项目级 .mcp.json 可以 通过 git 共享，并在首次使用时弹出审批提示。如果你 不小心关掉了那个提示，服务器就会保持禁用状态（pending/rejected）。运行 claude mcp reset-project-choices 可重新进行审批。把它与 MCP 基础以及智能体间协作的 A2A 结合起来看，就能掌握连接相关的全貌。

4. 在 Windows 上失败时（最常见的陷阱）

在原生 Windows 上，基于 npx 的 MCP 服务器以 spawn npx ENOENT / Failed to connect 连接失败——这极其常见。原因在于：Windows 的 npx 实际上是一个批处理外壳（npx.cmd），而 Node 的进程启动无法直接解析 .cmd。

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. 排查工作流

原因不明时，请自上而下处理。诀窍是 在归咎于 Claude Code 之前，先确认服务器能独立运行。

补充：添加过多的 MCP 服务器会让 工具定义占用上下文（尤其在始终加载的设置下）。Claude Code 默认通过工具搜索延迟加载工具定义，所以影响不大，但 禁用不用的服务器仍然是明智之举。过度占用上下文甚至可能触发 Prompt is too long。

6. 预防清单

避免在 MCP 连接上踩坑的习惯。

（1）本地脚本用绝对路径指定。（2）把服务器密钥放进每个服务器各自的 env（不是 settings.json）。（3）在 Windows 上用 cmd /c npx ... 包裹（或使用 WSL）。（4）把 .mcp.json 放在仓库根目录；注意 JSON 语法和未定义的 ${VAR}。（5）服务器不要把日志输出到 stdout（用 stderr）。（6）配置更改后要重新加载（完全重启 Desktop；重新批准项目服务器）。（7）卡住时，用 claude --debug mcp 加上独立启动服务器来隔离问题，必要时更新到最新版本。

总结

对于 Claude Code 的 MCP 服务器连接错误，最短路径就是 按 /mcp 的状态分为三大类。✗ failed 是本地启动问题（路径、环境变量、超时、配置位置——而且在 Windows 上要用 cmd /c 包裹 npx），△ needs authentication 是远程 OAuth（从 /mcp 认证），⏸ pending approval 是等待审批的项目服务器（在 /mcp 中审批；误拒可用 claude mcp reset-project-choices 修复）。

按顺序排查：（1）用 /mcp 看状态 -> （2）用 claude --debug mcp 看 stderr -> （3）独立启动 -> （4）MCP Inspector -> （5）完全重启 Desktop。在归咎于 Claude Code 之前，先确认服务器能独立运行，剩下的就缩小到配置或认证。只需三个习惯——把环境变量放进每个服务器各自的 env、把 .mcp.json 放在仓库根目录、把日志输出到 stderr——就能大幅减少故障。相关阅读：什么是 MCP、MCP 服务器的变现、Claude Code 错误汇总。

FAQ

Q. /mcp 显示“failed”。我该从哪里入手？
A. failed 多半是本地（stdio）服务器启动失败。请按顺序检查：（1）命令/脚本的路径（用绝对路径）、（2）必需的环境变量（放进每个服务器各自的 env）、（3）在 Windows 上用 cmd /c npx ... 包裹。如果原因仍不明朗，用 claude --debug mcp 读取服务器的 stderr，并先测试服务器能否在同一个 shell 里独立启动。

Q. 它显示“needs authentication”，工具用不了。
A. 这是远程（HTTP）服务器在请求认证（401/403）。打开 /mcp 并为该服务器执行认证，会进入浏览器中的 OAuth 批准流程。完成后，令牌会被安全存储并自动刷新。请注意，某些服务（Microsoft 365、Gmail、Google Calendar）不支持从 Claude Code 进行本地认证，必须改为在 claude.ai 上通过 Settings → Connectors 连接。

Q. 在 Windows 上我的 npx 服务器就是连不上。
A. Windows 的 npx 实际上是一个批处理外壳（npx.cmd），常常以 spawn npx ENOENT 启动失败。把 command 改为 cmd，把 args 改为 ["/c","npx","-y","package-name"] 来包裹它。在 WSL 下运行同样可靠。如果 where npx 能显示出路径却仍然失败，那几乎肯定就是这个 .cmd 问题。它可能在较新版本中已修复，所以也试试更新。

Q. 它显示“connected”却有 0 个工具。
A. 服务器启动成功了，但没有返回工具列表。一个常见原因是 stdio 服务器把日志写到 stdout 破坏了协议——务必把日志输出到 stderr。先从 /mcp 重新连接；如果还不行，用 claude --debug mcp 查看服务器的输出。

Q. 我配置了一个服务器，但它没出现在 /mcp 里。
A. 很可能是配置文件的位置有问题。共享的项目服务器要放进仓库根目录的 .mcp.json 里（在 .claude/ 下或 settings.json 里不会被读取）。未定义的 ${VAR} 也会导致配置解析失败。项目服务器需要首次审批；如果你关掉了提示，它就会保持 pending 状态——用 claude mcp reset-project-choices 重新审批。