MCP 装不上时，先分清它是哪种形态

MCP 装不上时，先分清它是哪种形态

粘贴一份别人跑通的配置，保存，打开会话，让它调工具。它说没有可用工具。配置文件还开着，字段名、缩进、引号都对。

这时候最省力的动作是把配置再对一遍，最费力的动作也是。因为「装不上」在这套东西里有三个互不相通的原因，它们长得几乎一样：配置没被读进去、宿主不支持这种形态、server 自己没工具。三者的修法没有任何重叠。

先把数据交代清楚：下面所有数字来自站内 10-28 的四轮采集文件，三轮单宿主全量（2026-10-28T05:38Z、06:33Z、08:29Z，mode=full，每轮 161 个 server，真机落格）加一轮跨宿主抽样（2026-10-28T01:02Z，mode=partial，6 个 server × 17 个宿主 = 102 格）。写稿时（10-29）没有更新的一轮，所以数字的时点是 10-28，不是今天。

第一步 · 认形态，161 个里 147 个是本地进程

形态只有两类，判据是配置形状而不是文档描述：

| 形态 | 数量 | 占比 | 判据 | 谁拉起进程 |

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

| stdio | 147 | 91.3% | 有 command 与 args | 宿主自己 fork 子进程 |

| http | 14 | 8.7% | 有 url / serverUrl / httpUrl 一类字段 | 服务在别处常驻 |

实测 161 个 server 里 147 个走 stdio，只有 14 个是远程。这个比例本身就有用：你在社区帖子里看到的绝大多数配置是 stdio，而「远程连不上」的经验帖天然稀少——样本量差了一个数量级。

形态认错，后面全是白工。同一个 server 换一套字段就换了一个形态，宿主对两边的支持是两套独立的能力，不是同一个开关的强弱。

第二步 · 宿主原生支不支持这一边

跨宿主那轮 102 格的结果是 pass 90、limited 4、fail 8。真正值得看的是那 12 个不绿的格子落在谁身上：

| 宿主 | 不绿格数 | 形态 | 站内判定 |

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

| claude-desktop | 3 | http | 配置层只支持 stdio，远程要走 Connectors 或本地桥 |

| gemini-cli | 2 | stdio | 真机未装上，逐 server 看 |

| qoder | 2 | stdio | 真机未装上，逐 server 看 |

| codebuddy | 1 | stdio | 真机未装上，逐 server 看 |

| lingma | 3 | http | 官方三处文档结论冲突，不做判断 |

| zed | 1 | stdio（有资源项） | 工具可用、资源取不到 |

前两行是两条方向相反的线：远程原生派在 stdio 上翻，本地 stdio 派在远程上翻。所以「换一个宿主试试」不是排查手段，它只是换个方向撞同一堵墙。17 个宿主的完整能力表在 按平台找 MCP，每条都标了证据档位。

这里有个反例必须写出来：gemini-cli 在 server-filesystem 与 server-memory 上实测 fail，但在 chrome-devtools 上 pass。三个都是 stdio。所以「这家不支持 stdio」这种结论也站不住——同一形态内部还会因为具体 server 分叉。判定要落到「这台 × 这个 server」这一格，不是落在「这台支不支持 stdio」这一行。

第三步 · 键名与字段，同一个意思有五种写法

这一步最容易被当成「配置写错了」，但它其实是「写对了别人的方言」。同样是远程条目：

| 宿主 | 远程键名 | 特别注意 |

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

| windsurf | serverUrl | 写 url 会一直连不上，且无明确报错 |

| gemini-cli | httpUrl 与 url | 前者是 Streamable HTTP，后者被当 SSE 解析 |

| workbuddy | type: "streamablehttp" | 没有连字符，写 streamable-http 连不上 |

| zed | 顶层 context_servers | 不是 mcpServers |

| opencode | 顶层 mcp | command 是数组；远程用 type: remote |

| roo-code | type 必填 | 不写 type 保存即报错，它不从 url 推断 |

判定口径：键名错的表现与「形态不支持」几乎一致——不生效、不报错。区别只有一处，键名能改对，形态不能。

codex-cli 是另一个维度：它是这些宿主里唯一用 TOML 的，JSON 段落直接粘过去等于没写。continue 用 YAML 数组，vscode-copilot 的键是 servers 而不是 mcpServers。格式层面的错和键名层面的错，症状一样，改的地方不一样。

第四步 · 生效条件，配了不等于读了

字段全对、形态也对，配置仍可能根本没进内存。站内记录里这一类有四条，档位不同：

• trae 的项目级 MCP 默认关闭，不打开开关，.trae/mcp.json 完全不生效（第三方记录，未回官方文档交叉验证）
• workbuddy 新条目要在连接器管理页手动 Trust 一次，配置正确也用不到工具（官方文档）
• claude-code 的项目级 server 需要人工批准后才生效（官方文档）
• gemini-cli 在未受信任目录下装不了 server，直接报错拒绝写入（本地真机实测撞到）

这四条的共同点：改文件永远试不出来。判据是看宿主自带的 server 列表里有没有这一条，而不是回头再读一遍 JSON。四条逐条的触发条件与出处见 装不上的原因 的 E 组。

两个跟形态无关的坑，别混进来

查完上面四步还是空，通常就落到这两类，它们跟宿主无关，也跟形态无关。

server 自己没有工具。 161 个里有 46 个 tools/list 返回空数组。这 46 个在三个宿主上实测全败，一个都没通。连接状态甚至可能是绿的，但没有任何可调的东西。判据是先绕开宿主单独验一次工具列表，方法在 数据是怎么来的；这一步能把「server 坏了」和「宿主不认」彻底分开。

启动比超时还慢。 161 个里 29 个启动超过 5000 ms，最慢两个分别是 53,217 ms 与 52,772 ms——首次要下依赖的那种。opencode 拉工具列表的默认超时是 5000 ms，是所有宿主里最短的，慢 server 在它这里会表现为「列表空」，在别家正常。

该按什么顺序动手

形态 → 宿主支持 → 键名字段 → 生效条件，最后才轮到 server 自身。这个顺序不是理论推导，是按「一次判定能排除多少格」排的：第一步一次排除 8.7% 的远程样本，第二步把范围压到一个宿主，第三步只改字符，第四步只点开关。越往后越便宜，越往前越省事。

如果想先确认手上的 server 长什么形状，server-filesystem 详情 是个典型样本：14 个工具、0 个资源、启动 4 秒上下，属于本地 stdio 派里最常见的那一类。远程形态的样子可以看 context7 详情：2 个工具、启动 1.4 秒，配置只有一行地址。

一个提醒：以上全部是「这台 × 这个 server」的单格实测，不是兼容性承诺。同一份表在 10-28 成立，不代表下周还成立——宿主的 CLI 版本一动，结论就可能变。术语口径统一在 名词解释，不确定哪个词指什么先查那里，比在群里问快。