MCP error -32000: Connection closed—

Q: 问：/mcp 显示 failed，应从哪里开始？

答：先看连接方式与 Issue:。stdio 的候选是命令、路径、环境变量和 stderr；HTTP 的候选是 URL、网络、服务器响应和认证。连接时固定的 Authorization 请求头被 401/403 拒绝，也会变为 failed，此时 Issue: 中会显示 HTTP 状态码。

Q: 问：它显示“needs authentication”，工具用不了。

答：处理方法取决于认证方式。使用 OAuth 的服务器应通过 /mcp 认证。使用自定义 headersHelper 时，工具调用返回 401/403 后，重新获取凭据再重试仍然失败，就会进入这个状态。如果 helper 提供 Authorization 请求头，Claude Code 不会切换到 OAuth；应修正凭据来源及返回的凭据，再重新连接。Microsoft 365、Gmail、Google Calendar 等由 Anthropic 提供的连接器，不支持从 Claude Code 进行本地 OAuth。如果用 claude mcp add 或 .mcp.json 添加后通过 /mcp 登录，会显示 is Anthropic-hosted and doesn't support local OAuth，此时应删除该注册，改为在 claude.ai 的连接器设置中连接。参见官方自定义认证说明。

Q: 问：Windows 上的 npx 服务器连不上。

答：查看 where.exe npx 和 Node/npm，并尝试用相同参数启动同一个包。如果问题出在 .cmd 文件的启动方式，可以用 cmd.exe /c npx ... 启动。在 WSL 中运行时，要在 Linux 一侧准备好 Node 和软件包。

Q: 问：已经 connected，但工具数量为 0。

答：先看该服务器是否设计为提供工具。如果只提供资源或提示词，工具为零是正常的。如果声明了工具能力却为零，/mcp 会给该服务器加上标记，此时请调查提供的能力、权限、服务器配置与日志，然后重新连接。stdio 诊断日志应写入 stderr，不要写入协议使用的 stdout 流。

Q: 问：已经配置服务器，但无法使用。

答：确认共享的项目 .mcp.json 位于项目根目录，再重新检查语法、作用范围和批准状态。未定义且没有默认值的 ${VAR} 会在警告后以字面文本加载，从而导致启动或认证失败。HTTP 配置还要写上 type。如果 claude mcp get 返回 ✘ Rejected，说明它被列入了某个设置文件的 disabledMcpjsonServers，除了重新批准，还要删除该项。

1. 这个错误到底在告诉你什么
2. 先用 /mcp 读取状态
3. 连接失败的主要原因与对策
4. 检查 Windows 上的 npx 启动
5. 排查工作流
6. 预防清单
总结
FAQ

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

/mcp

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

MCP 让 Claude Code 能够使用外部工具与数据。连接失败时，日志中有时会出现 MCP error -32000: Connection closed 这样一行。把状态、连接方式和错误详情这三者结合起来，就能缩小原因范围。本文按本地启动、远程通信与认证、配置和批准的顺序进行排查。

先看要点：（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 → 完成认证

⏸
my-server
pending approval → 批准

✗ failed = 连接失败，△ needs auth = 需要认证，⏸ pending approval = 等待批准。
failed 的原因，可以通过连接方式和 Issue: 的详情缩小范围。

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

连接关闭时，日志中会出现下面这一行。

MCP error -32000: Connection closed

MCP error -32000: Connection closed 表示 MCP 连接已关闭。MCP TypeScript SDK 将 -32000 分配给 ConnectionClosed，并在连接关闭时输出这句话（依据：SDK 的连接关闭处理）。这一行传达的只是“已关闭”这个结果，关闭的原因在它前面的日志里。服务器进程是在初始化前就退出了，还是连接建立后通信中断了，要在那里分辨。

即使配置正确，连接也可能断开。Issue #20713 是一位用户的报告：在 macOS 上使用 Claude Code 2.1.19 时，连接在初始化期间关闭。“竞态条件”这一原因只是报告者的推测，该 Issue 已于 2026 年 4 月以 not planned 关闭。自己报告问题时，请附上操作系统、版本、连接方式和已去除机密信息的日志。

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	需要登录或补充权限	OAuth 通过 `/mcp` 认证；`headersHelper` 要看凭据来源；Anthropic 提供的连接器要看 claude.ai 的连接器设置
⏸ pending approval	项目 `.mcp.json` 服务器等待批准。在 `claude mcp list` / `get` 中显示为 `⏸ Pending approval`	以交互模式启动 `claude` 并批准。若误拒绝：`claude mcp reset-project-choices`
✗ rejected	被列入某个设置文件 `disabledMcpjsonServers` 的 `.mcp.json` 服务器。只有 `claude mcp get <name>` 会显示 `✘ Rejected (see disabledMcpjsonServers in settings)`（`/mcp` 和 `claude mcp list` 中不显示）	在批准对话框中拒绝后，这一项会写入 `.claude/settings.local.json`。要撤销选择，使用 `reset-project-choices`；如果写在其他设置文件中，就删除该项

无论是本地启动失败还是远程通信失败，都会显示 failed。区分的线索在详情中：在 claude mcp list 中，HTTP 状态码或错误代码以及服务器返回的错误正文，会显示在 ✘ Failed to connect 这一行的末尾；在 claude mcp get <name> 和 /mcp 的详情界面中，则显示在 Issue: 这一行。连接时固定的 Authorization 请求头遭到 401/403 拒绝，也会显示 failed。

远程服务器在会话途中断开时，Claude Code 会自动尝试重新连接，期间 /mcp 会显示 pending（与等待批准是不同的含义）。5 次都失败而变为 failed 时，会收到 MCP server "<name>" disconnected · open /mcp to reconnect 的通知（需要重新认证时则变为 needs authentication）。stdio 服务器不会自动重连，需要从 /mcp 手动重新连接。另外，对于声明了工具能力却一个工具也没有提供的服务器，/mcp 会加上标记。只提供资源或提示词的服务器，工具数量为零也是正常的。参见官方服务器状态详情。

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

以下是排查连接失败和配置不匹配时的检查项。从与你的连接方式相符的项目开始依次查看。

ROOT CAUSES

按连接方式划分的检查项

1) 路径 / PATH

相对路径会以启动目录为基准而发生偏移。本地脚本请用绝对路径。找不到可执行文件时会报 spawn ... ENOENT。

2) 环境变量未传入

stdio 服务器专用的变量应设置在该服务器的 env 中。settings.json 中的 env 也会作用于会话和子进程，因此那里的值同样生效。

3) 启动超时

如果日志中出现启动超时，就调整 MCP_TIMEOUT（毫秒）。Bash 示例：MCP_TIMEOUT=10000 claude。PowerShell 中先设置 $env: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 不会显示该提示，直接加载服务器。仍不想加载的服务器，把它加入 disabledMcpjsonServers（官方 project 作用范围文档）。相关内容：MCP 基础、A2A。

4. 检查 Windows 上的 npx 启动

如果 Windows 报告 spawn npx ENOENT，先用 where.exe npx 查看可执行文件和 PATH。接着试试Node/npm 是否可用、指定的包能否单独启动。根据 Node 官方文档，Windows 上的 .cmd 文件无法单独执行，需要通过 shell 或 cmd.exe 启动。

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

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

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

在 WSL 中运行时，要在 Linux 一侧准备好 Node、软件包和环境变量。

5. 排查工作流

原因不明时，请自上而下依次进行。诀窍是在怀疑 Claude Code 之前，先确认服务器能否独立运行。

DIAGNOSE

自上而下逐层隔离

使用 /mcp 和 claude mcp list / get 查看状态，同时阅读 Issue: 和连接方式。

使用 claude --debug=mcp 获取MCP 初始化与连接日志。stdio 服务器还要阅读 stderr 的输出。

对于 stdio，用与配置相同的命令和变量单独启动试试。对于 HTTP，调查 URL、网络链路和响应码。

用 MCP Inspector（npx @modelcontextprotocol/inspector）单独验证服务器——可以在 UI 中试着获取工具列表并调用工具。

修改后重新连接，并尝试所需操作。如果仍然失败，请报告版本、连接方式和已去除机密信息的日志。

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

注意：Claude Code 默认通过工具搜索在需要时才加载定义，因此即使增加服务器，对上下文的影响也能保持很小。不过，指定了 alwaysLoad 的服务器，或关闭了工具搜索的配置，会在一开始就载入定义，所以用 /mcp disable <name> 停用不用的服务器更稳妥。上下文被占满会导致 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 常见错误汇总。

在 Codex 应用中能看到历史记录、却只有发送失败的症状，属于会话状态问题，而不是 MCP 问题。详见Codex“thread not found”：排查方法与恢复案例。

FAQ

问：/mcp 显示 failed，应从哪里开始？
答：先看连接方式与 Issue:。stdio 的候选是命令、路径、环境变量和 stderr；HTTP 的候选是 URL、网络、服务器响应和认证。连接时固定的 Authorization 请求头被 401/403 拒绝，也会变为 failed，此时 Issue: 中会显示 HTTP 状态码。

问：它显示“needs authentication”，工具用不了。
答：处理方法取决于认证方式。使用 OAuth 的服务器应通过 /mcp 认证。使用自定义 headersHelper 时，工具调用返回 401/403 后，重新获取凭据再重试仍然失败，就会进入这个状态。如果 helper 提供 Authorization 请求头，Claude Code 不会切换到 OAuth；应修正凭据来源及返回的凭据，再重新连接。Microsoft 365、Gmail、Google Calendar 等由 Anthropic 提供的连接器，不支持从 Claude Code 进行本地 OAuth。如果用 claude mcp add 或 .mcp.json 添加后通过 /mcp 登录，会显示 is Anthropic-hosted and doesn't support local OAuth，此时应删除该注册，改为在 claude.ai 的连接器设置中连接。参见官方自定义认证说明。

问：Windows 上的 npx 服务器连不上。
答：查看 where.exe npx 和 Node/npm，并尝试用相同参数启动同一个包。如果问题出在 .cmd 文件的启动方式，可以用 cmd.exe /c npx ... 启动。在 WSL 中运行时，要在 Linux 一侧准备好 Node 和软件包。

问：已经 connected，但工具数量为 0。
答：先看该服务器是否设计为提供工具。如果只提供资源或提示词，工具为零是正常的。如果声明了工具能力却为零，/mcp 会给该服务器加上标记，此时请调查提供的能力、权限、服务器配置与日志，然后重新连接。stdio 诊断日志应写入 stderr，不要写入协议使用的 stdout 流。

问：已经配置服务器，但无法使用。
答：确认共享的项目 .mcp.json 位于项目根目录，再重新检查语法、作用范围和批准状态。未定义且没有默认值的 ${VAR} 会在警告后以字面文本加载，从而导致启动或认证失败。HTTP 配置还要写上 type。如果 claude mcp get <name> 返回 ✘ Rejected，说明它被列入了某个设置文件的 disabledMcpjsonServers，除了重新批准，还要删除该项。

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