宿主切换前，按这三层逐级核对
同一个 MCP server 换到另一个宿主就调不出工具，多数不是 server 坏了。按 2026-11-02 全量快照重算的 2,737 格结果，把问题拆成配置结构、生效条件、可供调用三层，逐层给判据和动作，并标出哪些格子其实根本没被测到。
宿主切换前，按这三层逐级核对
同一个 server，在原来那个宿主里跑得好好的。把配置原样搬到另一个宿主，保存没报错，列表里也多了一行，可工具就是调不出来。这时候人通常会往两个方向猜：server 自己坏了，或者新宿主不支持它。两个猜测都偏了，真正的常见原因是它卡在三层中的某一层，而这三层要用完全不同的动作去解。
口径先说清。本文所有数字来自子站采集快照：采集时间 2026-11-02 19:53 UTC，mode=full，161 个 server × 17 个宿主 = 2,737 格，2026-11-07 现场重算。install 层 pass 1,516 格（55.4%），usable 层 pass 1,438 格（52.5%）。同一批条目换个宿主结论会变，这是常态；结论变了不等于坏了。宿主侧的能力与配置差异，可以先在宿主对照表里对一遍，再往下看。
三步判定的顺序不能反
顺序反了会白做功。配置结构错的那一层，再怎么调开关也不会生效；而已经连上、只是没东西可调的，改配置更是始终无效。
| 你看到的现象 | 卡在第几层 | 先做的一件事 |
|---|---|---|
| 保存就报错，字段标红或条目消失 | 第一层 · 配置结构 | 照该宿主官方示例重写键名，只搬命令与参数 |
| 保存成功，条目一直是灰的 | 第二层 · 生效条件 | 回界面找 Trust、approve、项目级开关 |
| 工具为空，或只出来一部分 | 第三层 · 可供调用 | 数工具数、对宿主上限，或换 server |
| 远程地址一连就失败 | 第一层 · 传输字段 | 先确认这家宿主把远程字段叫什么 |
第一层：宿主能不能读懂这份配置
MCP 规定了消息长什么样，没规定配置文件长什么样。于是每个宿主自己定一套，差异比你预期的大。
本轮实测 17 个宿主里只有 13 个用 mcpServers 作顶层键，另外 4 个分别是 servers（VS Code）、mcp_servers（Codex CLI）、context_servers（Zed）、mcp（OpenCode）。文件格式也不止 JSON：15 个用 JSON，Codex CLI 是 TOML，Continue 是 YAML。把 JSON 段直接粘进 TOML 不会报错，只会被当成注释或未知键忽略。
远程条目的字段名更碎，这一层是「配置看着对、就是连不上」的主要来源：
| 宿主 | 远程字段/取值 | 写错的后果 |
|---|---|---|
| Windsurf | serverUrl | 写 url 无明确报错，一直连不上 |
| Gemini CLI | httpUrl = Streamable HTTP，url = SSE | 字段写反会按 SSE 解析，握手失败 |
| WorkBuddy | type: streamablehttp（无连字符） | 写 streamable-http 连不上 |
| Roo Code | 必须显式写 type | 缺 type 保存即报错，它不从 url 推断 |
| OpenCode | 顶层 mcp，本地 command 是数组 | 粘 mcpServers 会被忽略，工具不出现 |
| Zed | 顶层 context_servers | 面板里看不到服务器 |
这一层没有通用模板。正确做法是每换一个宿主，只从它的官方示例复制结构，再填自己的命令和参数，结构本身不要搬。坑点全集在坑点库里按组归档，配置写法类统一归在 A 组。
还有一处要提醒：本轮的宿主能力表里，17 个宿主的证据强度并不一致——11 个有官方文档支撑，5 个只有第三方实测记录，1 个（通义灵码的远程支持）官方文档自相矛盾，只能标「未知」。所以第一层给出的键名字段，凡是标「第三方实测」的，都建议在自己机器上再确认一次。
第二层：读懂了，有没有真正生效
这一类最容易被误判成「配错了」。配置文件写对了，列表里也有条目，就是不起作用。本轮实测有 4 个宿主把「装」和「用」拆成了两步，中间那一步是安全确认：
- Trae：项目级 MCP 默认关闭，不打开「启用项目级 MCP」，
.trae/mcp.json完全不生效。 - Gemini CLI：在未 trust 的目录里执行写入会直接失败，报
Cannot modify settings in an untrusted workspace——这是权限拦截，不是配置写错。 - WorkBuddy：新条目不会自动生效，要去连接器管理页点 Trust 或启用，再重启会话。
- Claude Code：项目级 server 需要人工批准后才进入会话，
add成功不等于可用。
判据很简单：先回界面看有没有待确认提示，再回头改配置。改 JSON 解决不了权限问题。
第三层：连上了，有没有东西可调
状态是绿的、工具列表是空的，这一层和配置无关，和宿主兼容也基本无关。
一类是 server 自己就不提供工具。本轮实测 51 个 server 的 toolCount 为 0（48 个 stdio、3 个 http），其中 49 个启动耗时同样是 0，说明进程根本没起来。这类条目在按文档规则判定的宿主列上被记成了三种样子：46 个记 fail、3 个因需要授权或不可达记 na、2 个先记 pass 但备注写着「没有对外提供任何工具」。51 = 46 + 3 + 2，没有第四种记法。三种记法说的是同一件事：装不上、测不到、装上了也没得调。
另一类是被宿主截断。本轮实测 59 格 limited 只落在 4 列，而且每一列都恰好等于一条规则的全集：
| 宿主 | limited 格数 | 对应全集 | 原因 |
|---|---|---|---|
| Zed | 31 | resourceCount>0 的全部 31 个 server | 官方明确只支持 Tools 与 Prompts，不含 Resources |
| Cursor | 13 | toolCount>40 的全部 13 个 | 约 40 个工具软上限，跨 server 累计 |
| Windsurf | 4 | toolCount>100 的全部 4 个 | 约 100 个工具上限，比 Cursor 宽 |
| 通义灵码 | 11 | 14 个远程 server 中的 11 个 | 远程支持缺可靠资料，记「不做判断」 |
哪些格子其实没被测到
这一点决定了你该怎么读上面所有百分比。2,737 格的证据分三档：文档 1,344 格、真机 796 格、协议实测 597 格。真机只覆盖 3 列（每列 158 格），另 2 列（CodeBuddy、OpenCode）各 161 格全是 na——采集机上没装这两个平台的命令行工具。796 = 158×3 + 161×2，对得上。
na 合计 367 格：两个全 na 的列占 322 格，剩下 45 格来自 3 个需要授权或不可达的远程 server（free-agent-tools、huggingface、sentry）在其余 15 列上的记录。na 是「没测到」，不是「不支持」，两者不能混着算。想自己核对单个 server 的逐格结论，看单条详情页；想先知道判定规则本身，看判定方法。
三条可以带走的动作
一，先分层再动手。现象能直接对到层：报错在第一层，灰在第二层，空在第三层。
二，换宿主时只搬命令和参数，不搬配置结构。顶层键、格式、远程字段名这三处，一律以目标宿主的官方示例为准。
三，看到「连上了但没工具」，先去数 toolCount，而不是重装。51 个零工具 server 占了本轮 161 个样本的近三分之一，这个比例足以让「装不上」的直觉频频失效。
数据由子站采集器在 2026-11-02 19:53 UTC 以 mode=full 采集，2026-11-07 重算；文档列结论按各宿主官方规则推导，真机列结论为采集机实际安装后判定。
结论采集于 2026 年 11 月 7 日，实测方法见 数据怎么来的。