目录

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

/mcp

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

MCP 让 Claude Code 能够使用外部工具与数据。连接失败时，不要只看状态就判断原因，应结合连接方式和错误详情。本文依次介绍本地启动、远程通信与认证、配置和批准。

先看要点：（1）用以下命令读取状态与详情：/mcp 和 claude mcp get <name>。（2）failed 既可能出现在本地服务器，也可能出现在远程服务器。stdio 应检查命令和环境变量；HTTP 应检查 URL、网络、服务器响应与认证。（3）原因不明时，用 claude --debug=mcp 查看连接日志。只修改实际错误所指向的项目，再重新连接验证结果。

CLAUDE CODE · MCP STATUS

结合状态和详情查找原因

——遇到 failed，还要检查连接方式与错误详情

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed → 查看 Issue
△ notion needs auth → 用 /mcp 走 OAuth
⏸ my-server pending → 审批通过

✗ failed = 连接失败，△ needs auth = 检查认证，⏸ pending = 等待批准。
仅凭 failed 无法确定原因。请查看连接方式和错误详情。

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

例如，日志中可能出现下面的错误。不能只凭这句话认定服务器启动失败，还应查看前面的日志。

MCP error -32000: Connection closed

MCP error -32000: Connection closed 表示连接已关闭。MCP TypeScript SDK 将 -32000 分配给 ConnectionClosed。应从前面的日志查明关闭原因，例如服务器退出或连接中断。单凭这句话，无法判断进程是在初始化前退出，还是连接在初始化后断开。参见 SDK 的连接关闭处理。

不要认为相似报错一定有相同原因。 错误信息会随客户端、版本和服务器而变化。参考其他工具的解决办法时，应先确认它是否适用于自己的连接方式和日志。

也可能是配置之外的程序缺陷。例如，Issue #20713 收录了用户在 macOS 上使用 Claude Code 2.1.19 时初始化期间断开连接的报告。不要把用户的诊断当成 Anthropic 已确认的原因，也不要视为当前所有环境都受影响的故障。报告问题时，请附上操作系统、版本、连接方式和已去除机密信息的日志。

MCP 服务器常见的连接方式有两种。 （1）stdio（本地）——Claude Code 在自己的电脑上将服务器命令作为子进程启动，通过标准输入输出通信。（2）HTTP（远程）——通过 URL 连接云端服务器（旧的 SSE 已弃用）。“连不上”意味着什么，很大程度上取决于连接方式。

对于本地（stdio）服务器，应检查命令不存在、变量缺失、服务器退出或日志混入 stdout 等情况。对于远程（HTTP）服务器，应检查 URL 错误、网络问题、5xx 响应、超时和认证。两者都需要检查配置的位置、语法和作用范围。没有发生频率的依据，就不要认定原因“几乎都是认证”或“几乎都是路径”。

首先，记录状态与错误详情，确认连接使用 stdio 还是 HTTP。一次修改多项设置，会难以判断究竟是哪项生效。以下表为起点，一次排查一个相关原因。

2. 先用 /mcp 读取状态

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

状态含义优先排查处
✓ connected已连接，旁边显示工具数量如果应有工具却显示 0，请检查提供的能力、权限和日志
✗ failed本地或远程服务器连接失败Issue 详情与连接方式。HTTP 还应检查通信、服务器响应和固定认证请求头
△ needs authentication需要登录或补充权限，也应核对已配置的认证方式通过 /mcp 执行认证（在浏览器中批准）
⏸ pending approval项目 .mcp.json 服务器等待批准在 /mcp 中批准。若误拒绝：claude mcp reset-project-choices
✗ rejected被配置拒绝的项目服务器检查 disabledMcpjsonServers 和托管策略。reset-project-choices 用于重置自己的批准选择

failed 本身无法区分本地启动问题与远程通信问题。请查看 Issue: 中的 HTTP 状态码或错误正文，可通过 claude mcp get <name> 或 /mcp 的详情获取。连接时固定的 Authorization 请求头遭到 401/403 拒绝，也会显示 failed。此外，只提供资源或提示词的服务器，工具数量为零并不一定是错误。先确认服务器是否本就应该提供工具。参见官方服务器状态详情。

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

以下检查有助于排查连接失败和配置不匹配。先看与你的连接方式有关的项目。

ROOT CAUSES

按连接方式检查

1) 路径 / PATH
相对路径会以启动目录为基准而发生偏移。本地脚本请用绝对路径。找不到可执行文件时会报 spawn ... ENOENT。
2) 环境变量未传入
stdio 服务器专用的变量应设置在该服务器的 env 中。env 在 settings.json 中也会作用于会话和子进程，因此同样需要检查这些值。
3) 启动超时
较重的服务器来不及启动而失败。启动时提高 MCP_TIMEOUT（毫秒），例如 MCP_TIMEOUT=10000 claude。
4) 配置位置 / JSON
项目 .mcp.json 应放在项目根目录（不在 .claude/ 下，也不在 settings.json 中）。未定义且没有默认值的 ${VAR} 会触发警告，并保留为字面文本。
5) 污染 stdout
stdio 服务器若把日志写入 stdout，会破坏协议。请将日志写入 stderr。
6) 远程认证
如果需要 OAuth 登录，请通过 /mcp 认证。注意：固定认证请求头被拒绝时，状态会显示为 failed。

本地服务器应检查命令、环境变量和日志。
远程服务器应根据实际错误，检查URL、通信、服务器响应与认证。

可以共享项目 .mcp.json，但不要直接提交机密值。例如，引用 ${API_KEY}，并在各自环境中设置所需值。部分受保护的变量名，包括 Claude Code 自身的凭据，在远程 URL 和请求头中会展开为空字符串；请参见官方变量展开规则。交互式会话会请求批准项目服务器；相比之下，claude -p 和 SDK 通常不会显示该提示，便会加载服务器。拒绝设置等条件请查看官方 project 作用范围文档。另可参考 MCP 基础 与 A2A。

4. 检查 Windows 上的 npx 启动

如果 Windows 报告 spawn npx ENOENT，先用 where.exe npx 检查可执行文件和 PATH。还要确认Node/npm 是否正常、指定的包是否能够启动。Node 官方文档说明，.cmd 文件不能直接执行，并介绍了通过 shell 或 cmd.exe 启动的方法。但这并不意味着在所有 Claude Code 环境中直接指定 npx 都会失败。

如果问题出在启动方式，可以尝试 cmd.exe /c

如果问题出在 .cmd 文件的启动方式，可尝试以下形式。请将包名替换为服务器官方说明中的名称：

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

WSL 同样需要在 Linux 一侧准备好 Node、软件包和环境变量。切换到 WSL 并不保证解决问题，还应检查服务器支持的环境和 Claude Code 版本。

5. 排查工作流

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

DIAGNOSE

自上而下逐层隔离

1
使用 /mcp 和 claude mcp list / get 查看状态，同时阅读 Issue: 并确认连接方式。
2
使用 claude --debug=mcp 检查MCP 初始化与连接日志。stdio 服务器还应查看 stderr。
3
对于 stdio，用与配置相同的命令和变量测试单独启动。对于 HTTP，检查 URL、网络链路和响应码。
4
用 MCP Inspector（npx @modelcontextprotocol/inspector）单独验证服务器——在 UI 中查看工具列表并调用工具。
5
修改后重新连接，并尝试所需操作。如果仍然失败，请报告版本、连接方式和已去除机密信息的日志。

单独启动成功，不等于 MCP 连接和操作成功。
启动后，协议兼容性、权限、工具发现和客户端缺陷仍可能造成问题。

注意：添加过多 MCP 服务器，会让工具定义占用上下文（尤其是在始终加载的配置下）。Claude Code 默认通过工具搜索延迟加载定义，因此影响较小，但仍建议停用不用的服务器。 上下文过载还可能引发 Prompt is too long。

6. 预防清单

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

（1） 检查 stdio 可执行文件与脚本的实际路径。（2） 区分 stdio 变量与 HTTP 认证请求头，不把机密放入共享文件。（3） 在 Windows 上检查 where.exe npx 和 Node/npm；只有启动方式存在问题时，才尝试 cmd.exe /c。（4） 将 .mcp.json 放在项目根目录，并检查 JSON 语法、变量和批准状态。（5） 将 stdio 日志写入 stderr，而不是 stdout。（6） 每次只改一项，再重新连接并测试所需操作。

总结

排查 Claude Code MCP 连接错误时，应结合状态、连接方式和错误详情。failed 不仅表示本地启动失败：HTTP 通信失败、固定认证请求头被拒绝，也可能出现此状态。needs authentication 提示应检查认证，pending approval 则提示应检查项目服务器的批准状态。

按照以下顺序排查：阅读状态与 Issue: → 检查对应连接方式的日志 → 测试单独运行或通信 → 重新连接并验证操作。使用 claude --debug=mcp 选择调试类别，添加 --debug-file ./claude-mcp-debug.log 即可保存日志，分享前请删除机密信息。相关内容：MCP 是什么、MCP 服务器如何变现、Claude Code 常见错误汇总。

FAQ

问：/mcp 显示 failed，应从哪里开始？
答：检查连接方式与 Issue:。stdio 应检查命令、路径、环境变量和 stderr；HTTP 应检查 URL、网络、服务器响应和认证。连接时固定的 Authorization 请求头被 401/403 拒绝，也会出现 failed，因此不能只认定是本地启动问题。

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

问：Windows 上的 npx 服务器连不上。
答：检查 where.exe npx 和 Node/npm，并尝试用相同参数启动同一个包。如果问题出在 .cmd 文件的启动方式，可以使用 cmd.exe /c npx ...。WSL 也需要 Linux 一侧的环境正常。仅更换操作系统并不能保证解决问题。

问：已经 connected，但工具数量为 0。
答：先确认该服务器是否设计为提供工具。如果只提供资源或提示词，零工具并不一定是错误。如果应有工具，请检查提供的能力、权限、服务器配置与日志，然后重新连接。stdio 诊断日志应写入 stderr，不要写入协议使用的 stdout 流。

问：已经配置服务器，但无法使用。
答：确认共享的项目 .mcp.json 位于项目根目录，再检查语法、作用范围和批准状态。未定义且没有默认值的 ${VAR} 会触发警告，并在加载配置时保留为字面文本，可能导致启动或认证失败。HTTP 配置也应指定 type。只重复批准，无法解除拒绝设置或托管策略。

配置与命令参考：env 设置、CLI 参考、MCP 连接参考。