四类现象四套修法，别从头试一遍

四类现象四套修法，别从头试一遍

把同事跑通的配置粘过来，保存，重开一个会话，让它调工具。它说没有可用工具。

配置文件还开着，字段名对、缩进对、引号是半角的。这时候最省力的动作是把配置再对一遍，最费力的动作也是——因为「装不上」在这套东西里其实是四种互不相通的现象，它们长得几乎一样，而修法没有任何重叠。

先把数据交代清楚，后面每个数字都能回到站内页面复核。本文所有统计取自站内 2026-10-29 的一次采集文件，时间戳 2026-10-29T09:48:50Z（北京时间 17:48），mode=full、finalChunk=true、采集器版本 dev、Node v22.23.2。覆盖 161 个 server × 17 个宿主 = 2737 格，其中按证据分三档：真机 790 格、协议实测 555 格、文档推导 1392 格。写稿时点（10-30 上午）没有更新的一轮，所以下面的数字时点是 10-29，不是今天。

这 2737 格按可用性分是：通过 1583、有限 71、失败 1032、无法判定 51。真机 790 格里通过 319 格，占 40.4% —— 这个数比大多数人对「官方参考实现 + 官方文档」的预期低，原因在第二节。

先按现象分流，不要按报错找

宿主给出的提示几乎都是同一句「没有可用工具」或干脆沉默，报错码帮不上忙。可靠的分流依据只有你屏幕上看到什么：

| 你看到的 | 机制所在层 | 一分钟动作 | 这类在真机格里占多少 |

|---|---|---|---|

| 宿主列表里根本没有这个 server 的名字 | 生效条件（开关 / 批准 / 信任） | 看宿主的 server 列表，不是看 JSON | 不入格，表现为「配置未生效」 |

| 名字在、状态是绿的、工具是空的 | server 自己没有工具 | 绕开宿主单独问 tools/list | 230 格，全部失败 |

| 只出来一部分工具 | 宿主的工具数上限 | 把启用 server 的工具数加起来 | 22 格（文档档） |

| 拉工具列表超时 | 宿主超时阈值 vs server 启动耗时 | 量一次冷启动耗时 | 34 个 server 超过 5 秒 |

四行的共同点是：判定点全部在宿主侧或 server 侧的一端，不需要同时看两边。这也是分流比逐项猜快的原因——每一次判定都能先砍掉一批可能性，而不是把配置逐字再读一遍。

底盘：三分之一的真机失败，是 server 自己没工具

161 个 server 里有 49 个 toolCount 为 0。这 49 个在真机上的 230 格结果全部是失败，一格通过的都没有。

把它们剔掉之后，剩下 111 个 server 的 560 格实测结果里通过 319 格，通过率 57.0%——比不剔时的 40.4% 高出 16.6 个百分点。也就是说，「装不上」这个词被误用的比例不小：有近三分之一的失败格，症结不在安装动作，而在这批 server 本身没有可调用的东西。

这个数还解释了一个常见困惑：为什么同一份配置在别人机器上能用、在你这里不行。如果对方装的是有工具的那 111 个，你装的是那 49 个之一，两边看到的界面是一样的——都是空列表。

现象一 · 列表里没有名字，先在开关层找

这一类最容易被误判成 JSON 语法错，于是反复改格式。实际更常见的是配置根本没有被读进内存。

站内坑点库的 E 组记了四条，证据档位各不相同：Trae 的项目级 MCP 默认关闭，不开开关则配置文件完全不生效（第三方记录）；WorkBuddy 的新条目要到连接器管理页手动 Trust 一次（官方文档）；Claude Code 的项目级 server 需人工批准（官方文档）；Gemini CLI 在未受信任目录下装不了 server，直接报错拒绝写入（本地真机实测撞到）。四条完整出处见 装不上的原因。

判据只有一条：宿主自带的 server 列表里有没有这一条。有，问题在网络或命令层；没有，问题在开关层，此时改任何字符都不会有用。

现象二 · 连上了但工具是空的，先绕开宿主验

上文那 49 个零工具 server，症状都是「连接成功、握手完成、tools/list 返回空数组」。界面上连接状态甚至可能是绿的。

典型例子是 deepwiki：这个远程 server 在 5 个真机宿主上全部失败，失败原因逐条一致——它没有对外提供任何工具。换个宿主不会变好，因为缺口在 server 侧。

判定动作要单独做一次，不要靠宿主日志推断：先用协议层直接问一遍工具列表，再把结论带回宿主。这一步能把「server 坏了」与「宿主不认」彻底分开，方法见 数据是怎么来的。

现象三 · 只出来一部分，是撞了累计上限

这一类最好认，也最容易漏。Cursor 的上限是约 40 个工具，跨所有启用的 server 累计，不是单个 server 40。站内 161 个 server 里工具数超过 40 的有 16 个，最多的是 adbutler__mcp-server，628 个工具；另有 aiquila-mcp 316 个、softeria__ms-365-mcp-server 202 个。Windsurf 的门槛高一些，约 100 个，超过的 6 个。

症状特征是「昨天还能用，今天多装了一个 server 就不能用了」——因为上限是累计的。判定动作是把当前启用的所有 server 的工具数加起来，超了就精简启用集，或用宿主的工具筛选只暴露必要的几个。这两档的逐格明细留在 按平台找 MCP，每条都标了证据是官方文档还是第三方记录。

现象四 · 拉列表超时，先量冷启动

161 个 server 里 116 个记录了实测启动耗时：中位数 3,888 ms、p90 12,408 ms、最大 59,028 ms，超过 5 秒的 34 个，超过 10 秒的 15 个。

而 OpenCode 拉工具列表的默认超时是 5,000 ms，是 17 个宿主里最短的。按这组分布，p90 那一档 server 在 OpenCode 上会稳定超时，在默认 600,000 ms 的 Gemini CLI 上则不会。所以「同一个 server，同事能用我不能用」有时跟配置无关，只跟阈值的数量级有关。

这一档的处置只有两条：调大宿主侧的超时，或先把依赖预热好再接入。首次要下依赖的 Python server 是重灾区，59 秒那个就属于这一类。

同一形态内部也会分叉

到这里有个反例必须写出来，否则容易得出「某家不支持 stdio」这种过粗的结论。

五家跑真机的宿主，实测通过率差得很远：claude-code 68.4%（108 格）、opencode 67.7%（107 格）、gemini-cli 23.4%（37 格）、codebuddy 22.8%（36 格）、qoder 19.6%（31 格），每家在 158 个 server 上。同样是 stdio，第一梯队与第二梯队差了近三倍。

把「server 有工具、但这一格失败」的 241 格单独拎出来看，分布是：qoder 81、codebuddy 76、gemini-cli 75、opencode 5、claude-code 4。这 241 格不是配置写法问题，也不在 server 侧——同一批有工具的 server 在 claude-code 上大量通过，qoder 上大量失败。所以判定必须落到「这台宿主 × 这个 server」这一格，落在「这台支不支持 stdio」这一行会得出错误结论。

需要提醒证据边界：17 个宿主里只有 5 个跑过真机，另外 12 个宿主的结论来自官方文档与协议实测，最高只能标到「规则推导」。本文凡涉及这 12 个宿主的判断，都按这一档标注，不写成实测。

该按什么顺序动手

现象一 → 现象二 → 现象三 → 现象四。这个顺序不是按重要性排的，是按「一次判定能排除多少格」排的：

1. 现象一只看宿主列表，不花成本，却能先排除「配置没被读进去」这整片。
2. 现象二一次能排除 230 格真机失败，占真机总数的 29.1%，是单次判定里收益最大的一步。
3. 现象三只涉及 22 格（Cursor 16 + Windsurf 6），但一旦命中，改法是确定的。
4. 现象四落在 34 个 server 上，需要先量耗时才有结论，成本最高，放最后。

越往前越便宜，越往后越需要动手测。反过来按报错顺序试，通常会在现象一上耗掉半小时，而那里改任何字符都不会生效。

想先看一个「什么都对」的样本，可以打开 server-everything 详情：13 个工具、7 个资源项、启动约 3.8 秒，属于本地 stdio 派里最常见的那一类，也是官方协议全特性参考实现。术语口径统一在 名词解释，不确定某个词指什么先查那里。

最后一句提醒：以上全部是「这台 × 这个 server」的单格结论，不是兼容性承诺。宿主的 CLI 版本一变动，同一格的结果就可能翻转——本文的时点是 10-29，下次采集后这些数字要重新算。