MCP 装不上时先看证据等级：2,737 格里近一半是文档推断

MCP 出问题时的第一句话通常是「这个 server 装不上」。但「装不上」在这个生态里至少有三种完全不同的意思：文档里没写怎么装、装上了宿主认不出、认出了工具调不动。三种混在一起讨论，就会得出互相矛盾的结论。

2026-11-02 的全量快照把这件事拆成三层来判：161 个 MCP server × 17 个宿主 = 2,737 格，每一格只落在一层证据上。文档层 1,344 格、真机层 796 格、协议实测层 597 格，三层通过率分别是 93.0%、23.6%、0，差了一个量级。

所以排错的第一步不是改配置，而是先确定手上这条信息属于哪一层。层搞错了，后面全是白做。整张矩阵按层怎么切分，可以对照 MCP 兼容矩阵的逐格实测记录；条目本身在名录里的分布，也可以先在 站内条目清单 过一遍再动手。

先对号：症状决定你该看哪一层

你看到的现象	卡在哪一层	下一步动作
文档里没写怎么装，只写了「支持」	文档层	找可执行命令，找不到就换 server
命令能跑，宿主列表里没有条目	真机层	查进程、参数、运行时版本
列表有条目，状态一直是灰的	真机层	查信任开关、项目级批准
状态绿，工具列表是空的	协议层	数工具数，看是否只提供 resources
同一台机器能跑，换一台就不行	真机层	查包源与网络出口

第一层：文档推断，占 49.1%

1,344 格里 pass 1,250 格，93.0%。这个数字最容易被读成「生态已经成熟」，毕竟九成以上都能用。

它衡量的其实是「文档写清楚了」。README 里写着 npx -y xxx，这一格就记 pass；至于这条命令在目标宿主的环境里能不能跑起来，文档层完全不看。采样时每格只判一次，不含重试，连「偶尔失败」都体现不出来。

所以文档层 pass 的正确用法是当候选，不是当可用。这一层判 pass 的条目在名录里长什么样，可以先在 站内条目清单 里过一遍。

第二层：真机实测，占 29.1%

796 格真装了：pass 188 格、23.6%，fail 286 格，na 322 格。把 na 剔掉，真机测到的 474 格里通过率 39.7%。

从 93.0% 掉到 23.6%，掉的就是「文档写了」和「这台机器上真能跑」之间的落差。这一层的失败大多不在协议，而在进程：命令不在 PATH、Node 版本不符、路径带空格、依赖拉不下来。

顺带说启动。有值的 112 个 server 里，启动耗时中位 3,866 ms、p90 12,236 ms、最大 55,285 ms。健康检查若卡在 3 秒，一半 server 第一轮就被判死，这类 fail 记在真机层，跟协议无关。

第三层：协议实测，占 21.8%

597 格走协议层握手探测：pass 0 格、fail 552 格、na 45 格。

0 这个数字看着极端，但它反映的是探测口径——这套探测在握手阶段就停住了，没有一格走到工具调用。它只能说明「按这套协议探测法，没有一个 server 走通」，推不出「这些 server 全坏」：同一批 server 在真机层还有 188 格是 pass。

四个坑，按踩到的顺序拆

坑一 · 把文档写了装法当成装得上

现象：README 里有安装命令，复制过去就报错。
原因：文档层判的是「有没有写」，不是「写了能不能跑」。93.0% 说的是文档完整度，不是可用率。
动作：把文档当线索，先在一台干净机器上跑一次，跑通了再往下走。

坑二 · 只看 install 通过就以为能用

现象：npm i 或 npx 成功了，宿主里还是空的。
原因：装包成功只说明文件落地，不代表宿主读到了配置。传输方式、键名、启动命令任一处不对，宿主就当条目不存在，而且往往不报错。
动作：装完立刻回宿主数条目、看状态，别等到调用的时候才发现。

坑三 · 把 stdio 和 http 放进同一张表比

现象：看到 stdio 51.9%、http 59.2%，得出「远程更稳」。
原因：stdio 有 147 个 server、2,499 格，http 只有 14 个、238 格，样本结构完全不同。stdio 的失败大量发生在启动，http 的失败大量发生在字段语义。
动作：分开统计、分开排错。跨传输比百分比，比出来的差异大半是样本构成的差异。

坑四 · 把 na 当成 fail

现象：把 367 格 na 算进分母，得出某宿主 0% 可用。
原因：na 是「这次没测到」，比如采集机没装该平台的命令行工具。整列 na 的宿主（codebuddy、opencode）就是这样落到 0 的，不是「一个都装不上」。
动作：na 单列，不参与横向比较；要么补测，要么在结论里注明这一行不可比。

排错顺序，照抄即可

1. 确认 server 的传输方式，stdio 与 http 的排查路径不同。
2. 用目标宿主的官方示例当模板，只搬命令与参数，别搬结构。
3. 手动跑一次启动命令，看进程能不能起来、有没有错输出。
4. 回宿主数条目，再数工具数（中位 8.5，最大 628）。
5. 工具数为 0 时，先确认它是否只提供 resources 或 prompts。
6. 全部对上仍不通，换一个宿主复现，区分是 server 侧还是宿主侧。

第 6 步常被跳过，也最有效。同一批 server 在七个宿主上并列 68.3%，到 codebuddy、opencode 是 0，宿主侧的实现差异足以把结论整个翻过来。

总结

三层证据的通过率差一个量级，所以「MCP 能不能用」这句话必须先补上「哪一层」；分层口径与逐格结果见 MCP 兼容矩阵的逐格实测记录。

适合与不适合

适合：正在给团队写 MCP 接入检查清单的人；遇到「状态绿但工具空」想先分类再动手的人；需要把文档结论和实测结论分开汇报的人。
不适合：只在单一宿主、单一 server 上试过一次就下结论的人；要「装了就有得调」的人，2,737 格里 pass 只占 52.5%；在内网或代理后部署、指望这份快照能替你回答出网问题的人。

标签：MCP、DeepSeek Harness、证据分层、排错清单

本文由 DeepSeek Harness Hub 自动整理，数据来源于 MCP 采集快照（2026-11-02）。