MCP 装不上：5 类原因，按这个顺序排查

先把结论放前面：装不上时不要急着重装客户端。按下面五类顺序判断，大部分问题能在一分钟内定位到具体原因。

判断依据来自本站 2026-10-24 那一轮采集：295 个 MCP 样本里，155 个握手成功，140 个失败。失败样本的错误分布是——连接被关闭 111 次、请求超时 17 次、HTTP 请求失败 9 次、网络不可达 2 次、401 一次。

第一步：先看错误长什么样

错误信息决定了往哪一类查。实测里出现最多的是这四种：

• MCP error -32000: Connection closed —— 进程根本没起来，或者起来之后立刻退出。属于本地启动类问题。
• MCP error -32001: Request timed out —— 进程起来了，但在规定时间内没有应答。属于超时类问题。
• Non-200 status code 401 —— 远端明确要求授权。属于授权类问题。
• fetch failed —— 本机网络、DNS 或代理不通。属于网络类问题。

前三类是这篇文章要解决的；如果是 fetch failed，先确认代理和 DNS，再回来看下文。

第二步：按五类原因对号

A 配置写法不对：抄别家的 JSON 一定会踩

同一个 MCP，在不同客户端里的配置结构并不一样。实测确认的差异至少有这几条：

• Windsurf 远程配置的键名是 serverUrl，不是 url。
• Roo Code 的 URL 配置必须显式写 type，缺了立即报错。
• WorkBuddy 的远程 type 写作 streamablehttp，没有连字符。
• Gemini CLI 远程有两个字段 httpUrl 与 url，语义不同，填错会静默不生效。
• Zed 用的是 context_servers，不是常见的 mcpServers。
• OpenCode 顶层键是 mcp，且 command 是数组而不是字符串。

这类问题的特征是：配置看起来完全正确，但客户端说找不到 server。判断方法很简单——把该客户端官方 README 里的示例先跑通，再往里填目标 MCP 的参数。看不懂字段含义时，先查名词解释。

B 平台本身没有这个能力

有些 MCP 装不上不是配置问题，是客户端根本不支持这种传输或原语：

• Claude Desktop 只认 stdio，远程 server 一个都装不上，这不是写法问题。
• Zed 不支持 resources 原语，带资源项的 MCP 会在能力协商阶段被降级。
• 0 个工具的 server 在任何宿主上都没有意义——连上了也没有可调用的能力。

判断方法：先确认这个 MCP 是本地还是远程，再对照按平台找 MCP里对应客户端的结论。远程 MCP 在只支持 stdio 的客户端上，怎么改配置都不会成功。

C 能连上，但被截断或超时

这类问题的表现是「装了、也连上了，但工具少了一半，或者提示超时」：

• Cursor 大约有 40 个工具的上限，超出部分会被截断。
• OpenCode 拉取工具列表默认只等 5 秒，慢一点的 server 直接判定失败。

实测里工具体量最大的样本是 premiere-pro-mcp，单个 server 声明了 434 个工具；smartbear-mcp 是 309 个。这类 server 在带工具上限的客户端上必然被截断，不是它坏了，也不是你配错了。

处置只有两条：精简该 server 暴露的工具，或者换一个没有硬上限的客户端。

D 需要账号授权

远程 MCP 里，头部服务几乎全部要求授权。实测中 Notion、Linear、Atlassian、Figma、Stripe、Supabase、Neon、GitHub、Slack、Vercel 的官方端点全部返回 401。

要区分两件事：

• 401 说明端点活着，只是你没给凭据。它和「服务挂了」是两回事。
• 需要 OAuth 的 server，在没有浏览器的环境里验证不了，例如 Sentry 的 OAuth 流程、Gemini CLI 在无头环境下的授权发现。

判断方法：先看这个服务是否提供 API Key 通道；只有 OAuth 的，按客户端文档走一遍授权，别在无凭据环境里反复重试。

E 配了但不生效

最容易被误判成「MCP 有问题」的一类。配置没错、进程也起来了，但工具列表是空的：

• Trae 的项目级 MCP 默认关闭，配置写了也不生效。
• Gemini CLI 在未受信任的目录下不允许加载 MCP server。
• WorkBuddy 的新配置不会自动生效，需要手动点一次 Trust。
• Claude Code 的项目级 server 需要人工批准。

这一类的共同点是：存在一个与配置无关的开关。查的顺序是「项目级还是全局级 → 是否已信任 → 是否需要批准」，不要从配置语法开始查。

第三步：按这个顺序自检

1. 读错误信息，先分清是启动类、超时类、授权类还是网络类。
2. 用该客户端官方示例跑通一次，确认客户端本身可用。
3. 对照本文 A 类，逐字核对键名与字段类型。
4. 确认该客户端支持目标 MCP 的传输方式（B 类）。
5. 工具数是否超过客户端上限（C 类）。
6. 远端服务是否需要授权、凭据是否已配（D 类）。
7. 项目级配置是否已信任或批准（E 类）。

七步都过了仍然不通，用一个最小样本做对照实验：把 server-memory 用同一份配置接进去。它能通、目标 server 不通，问题在目标 server；它也不通，问题在你的环境或客户端。

什么时候可以断定不是你的问题

用最小样本对照之后，如果同一客户端、同一份配置下只有目标 MCP 失败，就可以基本判定问题在该 server 一侧——常见原因是启动命令的包版本变了、需要额外的系统依赖、或者进程启动后立即退出。

这时不要再改配置。去看该 MCP 页面上记录的启动耗时、退出原因和平台结论，比盲目重装有效。playwright-mcp 和 context7 是两个可以直接对照的样本：前者是本地 stdio，后者是远程 HTTP，分别代表两类传输的正常形态。

数据口径

本文所有数字来自 2026-10-24 那一轮采集，共 295 个样本、17 个客户端。这 295 个样本中有一部分页面尚未上线，站内当前可查的是已发布的部分——口径以采集轮次为准，不以页面数量为准。「握手成功」只代表协议层连上并能列出工具，不代表装上就能用——需要授权的服务在授权前拿不到工具。判定方法与证据分级见数据是怎么来的，按症状归类的完整清单见装不上的原因。