MCP 装不上，先改配置还是先对症状？

张皓181

206人浏览 · 2026-11-05 07:53:26

张皓181 · 2026-11-05 07:53:26 发布

MCP 装不上，先改配置还是先对症状？

MCP server 装不上时，多数人的第一反应是改 JSON：换键名、加 mcpServers、把 command 改成 npx。这套动作有一半是白做的——不同宿主失败的原因根本不在同一层。下面按症状分四类，每类给出判据和动作，数字全部来自 2026-11-02 19:53 UTC 生成的采集快照（161 个 server × 17 个宿主 = 2,737 格，模式 full）。

一、先看这张症状表

症状	更可能的层	先做的事	不要做的事
宿主里能看到 server，但工具列表是空的	server 本身没暴露工具	数工具数	改键名
换一台机器就装不上，同一份配置	宿主版本或本地环境	对齐宿主版本	重写配置
配置检查全绿，实际调用失败	文档推断与真机结果不一致	看证据级别	相信清单上的绿勾
连接一直转圈	启动耗时或网络	量启动耗时	反复重装

这张表背后有一个统计事实：2,737 格里 pass 1,438、fail 873、limited 59、na 367。na 那 367 格不是失败，而是「没测到」——采集机没装对应平台的命令行工具。

二、四个具体故障

坑一 · 连上了，但工具是空的

现象：宿主显示已连接，工具栏里没有任何可调用的工具。
原因：161 个 server 里有 51 个的工具数是 0，其中 8 个是测试夹具，剩下 43 个是真实 server。它们有的只提供 resource 不提供 tool，有的启动后需要额外参数才注册工具。
解决：先看 toolCount，等于 0 就别在配置上耗时间；再确认它属于 stdio 还是 http（本次快照 147 个 stdio、14 个 http），http 型的工具注册发生在握手之后。

坑二 · 换个宿主就装不上

现象：同一份 server 在 A 宿主能用，在 B 宿主报配置不合法。
原因：宿主的判定规则不同。本次快照里 7 个宿主（trae、vscode-copilot、codex-cli、cline、roo-code、continue、workbuddy）的 161 格判定序列完全一致，各 110 通过；而真机实测的 gemini-cli 只有 40 格通过（24.8%）、qoder 39 格（24.2%）。
解决：先确认真机通过率，不要拿「文档说支持」当结论。

坑三 · 文档说能装，真机装不上

现象：清单上打勾，实际连接失败。
原因：有 72 个 server 在文档证据下判 pass、在真机证据下判 fail。文档推断共 1,344 格（pass 1,250），真机只有 796 格（pass 188）。
解决：看证据级别那一列。真机 796 格里通过的只有 188 格，通过率 23.6%。

坑四 · 一直在转圈

现象：命令发出后长时间无响应，最后超时。
原因：启动耗时差异极大。112 个有耗时数据的 server 中位数 3,866 ms，最长 55,285 ms（b1-mcp-server），最快 212 ms（dpharness-mcp）。
解决：把宿主超时调到中位数的两倍以上再试；超过 20 秒的 server 单独隔离排查，不要和正常 server 混在一张配置里。

三、按顺序排查的四步

数工具：tools/list 返回为空 → 问题在 server 侧，跳过配置排查；可用完整插件清单与汉化避坑指南里同名的 server 条目做参照；
看证据：清单上的结论是「文档推断」还是「真机实测」，两者结论可能相反；
量耗时：启动超过 5 秒的，先解决稳定性再谈功能；
查宿主：同一份配置换宿主复现，能复现就不是配置问题。

协议层的实测结果也值得知道：597 个「协议实测」格里没有一格判 pass，其中 552 格记「这个平台用不了它」、45 格记「本机网络连不上这个服务」。这说明协议探测目前只产出否定结论，不能当作正向验证。