文档绿只证明 MCP server 起来了：三个宿主 99% 到 32%

文档绿只证明 MCP server 起来了：三个宿主 99% 到 32%

先说结论：兼容表里那个绿色，绝大多数情况下不代表「你这个宿主能用它」，只代表「这台 server 自己起来了」。这两件事在数据上可以分开验证，而且分得非常干净。

口径交代。数据取自子站采集机的汇总文件 /opt/mcp-collect/data/mcp-data.json，generatedAt 是 2026-11-02T19:53:24Z（北京时间 2026-11-03 03:53），mode 为 full、finalChunk 为 true，161 个 server 乘 17 个宿主共 2737 格。剔掉 8 个 isFixture 测试样本后是 153 个 server、2601 格：pass 1339、fail 856、limited 55、na 351。下面每个数字都是 2026-11-04 在原始 JSON 上现场重算的，不是二手汇编。想先查逐宿主的配置键名与能力边界，打开宿主能力对照；想按现象对号找坑，见坑点清单。

先摆两个集合：103 和 103

判断「文档层在测什么」，最直接的办法是看它给谁出结论、不给谁出结论。于是做一次集合比对：

逐个比对后，A 减 B 是空集，B 减 A 也是空集。两个集合完全相等，一个不多一个不少。

这件事的含义比数字本身重要。文档层判的是「这份配置格式，这个宿主认不认」，如果它真的在量宿主差异，那 A 里应该既有能起来的 server，也有起不来的 server —— 起不来的那批，配置格式照样可能被宿主接受。但实测不是这样：文档层只在能起来的 server 上给绿，起不来的一律不给结论或者直接给红。

换句话说，文档层是启动结果的下游指标，不是宿主兼容的上游判据。实测下来，文档层这 1248 格只落在 12 个文档宿主上，每个宿主 103 格左右；50 个零工具 server 里有 46 个在这 12 列上一格都没有。它遮住了真正想看的那个变量。

真机层把宿主差异说清楚了

同一批 103 个 server，真机层给出的答案完全是另一幅样子。真机只覆盖 5 个宿主，其中 codebuddy 与 opencode 的 hostAvailability 是 available:false、原因写的是「未知原因」，两列各 153 格全是未测，所以真正能出结论的只有 3 个宿主：

同一批 server、同一份配置、同一台机器，换个宿主通过率从 99.0% 掉到 32.0%。实测这中间差了 67 个百分点，比任何「配置写法改对一版」带来的提升都大。这也解释了一个常见困惑：有人照着文档把配置写得一字不差，换台机器就是不通 —— 不是写得不对，是宿主这一层本来就不一样。

顺带把两个方向都算清楚：103 个非零工具 server 在 claude-code 上只失败 1 个，在 gemini-cli 上失败 69 个，在 qoder 上失败 70 个。失败集中在两个宿主，不在 server 侧。

反过来看：文档零绿的那 47 个

有真机可测格的 server 一共 150 个。除了上面那 103 个，剩下 47 个在文档层一格绿都没有 —— 它们的真机结果高度一致：

• 实测这 47 个 server 共有 141 个真机可测格，判 pass 的是 0 个，141 格全部 fail。
• 这 47 个的工具数全部是 0，也就是 50 个零工具 server 里凡是有真机格的那批。
• 其中 46 个 startupMs 也是 0，即进程根本没起来；第 47 个 structured-world__gitlab-mcp 启动耗时 22675 毫秒，12 个文档格全判 fail。

所以「整行红」这种形态，成因通常是进程层，不是配置层。真机 141 格零通过不是巧合，是同一件事被记了 141 次。

三步判定，按这个顺序走

第一步看这一行有没有任何一格绿。一格都没有、且工具数是 0，直接放弃这台 server，不要去动你的 JSON —— 换宿主、改键名、加超时都救不回来，问题在它自己能不能启动。

第二步看绿格的证据。有绿格意味着 server 起来了，但还只是「配置格式被接受」。判断方法在判定方法里写得很细，一句话概括：同一行里真机格的结果，才代表它在你这类宿主上的实际表现。

第三步看你自己的宿主在不在真机覆盖里。17 个宿主里只有 3 个有真机结论，剩下 12 个（trae、lingma、cursor、zed、cline、roo-code、continue、windsurf、vscode-copilot、codex-cli、claude-desktop、workbuddy）的真机格是 0。你如果用的是这 12 个之一，那张表对你的准确含义是「配置格式它认」，不是「装上就能用」。这 12 个宿主的具体约束记在宿主能力对照里，结论等级最高只到「规则推导」。

三个坑，都是我自己先踩过的

坑一 · 把文档绿读成宿主兼容

现象：挑了一个在 Cursor 列显示通过的 server，配置粘进去，工具列表是空的。原因：那一格来自文档判定，它证明的是 server 能起来、配置格式被接受，不证明 Cursor 真的把工具列出来了 —— 而 Cursor 恰恰是那 12 个没有真机格的宿主之一。解决：先确认自己宿主的真机格数量，是 0 就把绿格当「待验证」，不当「可用」。

坑二 · 见到整行红就去改配置

现象：某个 server 在 17 个宿主上全是红，于是怀疑是 mcpServers 键名写错了，改了三版还是红。原因：这台 server 的工具数是 0、启动耗时是 0，进程根本没起来；141 个真机格零通过说的都是同一件事。解决：先跑一次启动，看进程能不能起、工具列表能不能拉出来，再谈配置。零工具 server 的判定可以看server-memory这类正常样本做对照。

坑三 · 拿 17 列横向比宿主

现象：看到某个宿主「110 格绿」，就判断这个宿主兼容性最好。原因：那 110 格里真机格可能是 0，全是文档判定的结果；而文档判定在 12 个宿主上给的是同一份答案（都按同一套格式规则推），横着比等于把同一份证据数了 12 遍。解决：只在有真机格的宿主之间比，目前就是 claude-code、gemini-cli、qoder 三个。

收尾

一句话记住这个顺序：先看有没有绿格（server 起没起来），再看绿格的证据（文档还是真机），最后看你的宿主在不在真机覆盖里。三步都过，才值得去调参数。术语与字段含义在术语表，逐宿主的配置写法差异在宿主能力对照，按现象反查原因在坑点清单。

数据会变，方法不变。下一次采集如果补上了 codebuddy 与 opencode 的真机结果，上面那张三行表会变成五行，但「文档绿 ≠ 宿主兼容」这条判据不会变。