装不上的原因
按「为什么装不上」分类，不按平台分类。每条都写了现象和具体怎么改，标注了依据。
A · 配置写法不对，抄别家的就用不了
6 条Windsurf 远程键名是 serverUrl，不是 url实测影响 54 条结论
- 什么时候会遇到
- 远程 server 配置里写了 url
- 你会看到什么
- 配置看着对，但一直连不上，无明确报错
- 怎么解决
- 把 url 改成 serverUrl，headers 保持对象形式
Windsurf依据：第三方实测
Roo Code 的 URL 配置必须显式写 type，否则立即报错实测影响 48 条结论
- 什么时候会遇到
- 用 url 配置远程 server 但没写 type
- 你会看到什么
- 保存即报错：无法从 url 推断传输类型
- 怎么解决
- 显式写 type: "streamable-http"（推荐）或 "sse"（旧服务）
RCRoo Code依据：官方文档
WorkBuddy 的远程 type 写作 streamablehttp，没有连字符实测影响 48 条结论
- 什么时候会遇到
- 照别家习惯写 type: "streamable-http"
- 你会看到什么
- 连接失败或工具不加载
- 怎么解决
- 写 type: "streamablehttp"；或写 "http" / "sse"
WBWorkBuddy依据：官方文档
Gemini CLI 远程有两个字段：httpUrl 与 url，语义不同实测影响 258 条结论
- 什么时候会遇到
- 远程 server 配置
- 你会看到什么
- 用 url 连 Streamable HTTP 端点会按 SSE 解析，握手失败
- 怎么解决
- Streamable HTTP 用 httpUrl；旧 SSE 服务才用 url
Gemini CLI依据：官方文档
OpenCode 顶层键是 mcp，且 command 是数组实测影响 53 条结论
- 什么时候会遇到
- 直接粘贴 Claude / Cursor 的 mcpServers 配置
- 你会看到什么
- 配置被忽略，工具不出现
- 怎么解决
- 改成 mcp 键；本地写 type: local、command: ["npx","-y","包名"]；远程写 type: remote
OpenCode依据：官方文档
Zed 用 context_servers 而不是 mcpServers实测影响 85 条结论
- 什么时候会遇到
- 把 mcpServers 配置粘进 Zed settings
- 你会看到什么
- AI 面板里看不到服务器
- 怎么解决
- 顶层键改为 context_servers；本地写 command/args/env，远程写 url/headers
Zed依据：官方文档
B · 平台本身没这个能力
3 条Claude Desktop 只认 stdio，远程 server 一个都装不上实测影响 58 条结论
- 什么时候会遇到
- server 的 transport 是 streamable-http 或 sse
- 你会看到什么
- 配置里写 url 不生效；界面上看不到任何工具，也不报错
- 怎么解决
- 二选一：①用 Connectors UI 走 OAuth 连接；②用 mcp-remote 把远程 URL 包成本地可执行命令，再按 stdio 配置
Claude 桌面版依据：官方文档
Zed 不支持 resources 原语实测影响 85 条结论
- 什么时候会遇到
- server 的 resources/list 返回数量 > 0
- 你会看到什么
- 工具能用，但资源类内容完全取不到，界面无提示
- 怎么解决
- 若依赖 resources 传上下文，改用工具返回内容承载；或换宿主
Zed依据：官方文档
0 个工具的 server 在哪个宿主都用不了实测影响 1365 条结论
- 什么时候会遇到
- tools/list 返回空数组（常见于配置错、路径错、权限不足）
- 你会看到什么
- 连接状态可能是绿的，但没有任何可用工具
- 怎么解决
- 先单独用 MCP Inspector 或本工具验证 tools/list；确认是 server 侧问题再排查宿主
Claude CodeGemini CLIQdQoderTrae灵通义灵码Claude 桌面版CursorVS CodeCodex CLIWindsurfZedClineRCRoo CodeOpenCodeCoContinueWBWorkBuddy依据：本站实测
C · 能连上，但工具太多或太慢
2 条Cursor 约 40 个工具上限，工具多的 server 会被截断实测影响 61 条结论
- 什么时候会遇到
- 单个或多个 server 累计工具数超过约 40
- 你会看到什么
- 部分工具莫名不可见，模型说找不到工具
- 怎么解决
- 精简启用集；或用 Cursor 的工具筛选只暴露必要工具
Cursor依据：第三方实测
OpenCode 拉工具列表默认只等 5 秒实测影响 53 条结论
- 什么时候会遇到
- server 启动慢或首字节超过 5000ms（如首次下载依赖的 Python server）
- 你会看到什么
- 工具列表为空或连接超时，但同一 server 在别家能用
- 怎么解决
- 配置里显式调大 timeout（毫秒）；或先预热依赖缓存再接入
OpenCode依据：官方文档
D · 需要账号授权，测不了
2 条需要 OAuth 的远程 server，无凭据环境验证不了实测影响 1365 条结论
- 什么时候会遇到
- server 未携带凭据时返回 401 / 要求浏览器授权
- 你会看到什么
- 连接直接失败，容易被误判成「这个 server 不可用」
- 怎么解决
- 先完成 OAuth 再测；CI 环境改用带 token 的请求头或静态凭据代理
Claude CodeGemini CLIQdQoderTrae灵通义灵码Claude 桌面版CursorVS CodeCodex CLIWindsurfZedClineRCRoo CodeOpenCodeCoContinueWBWorkBuddy依据：本站实测
Gemini CLI 的 OAuth 自动发现需要本机浏览器实测影响 258 条结论
- 什么时候会遇到
- 远程 server 触发 OAuth，但运行在无头服务器 / 纯 SSH 环境
- 你会看到什么
- 认证流程走不下去，报错或卡住
- 怎么解决
- 在本机带浏览器完成一次授权并把凭据带过去；或改用静态 token 头
Gemini CLI依据：官方文档
E · 配了但不生效，要额外开开关
4 条Trae 项目级 MCP 默认关闭，配置写了也不生效实测影响 48 条结论
- 什么时候会遇到
- 在 .trae/mcp.json 写配置但没开开关
- 你会看到什么
- 配置文件存在，但 MCP 列表为空
- 怎么解决
- 设置 → MCP → 打开「启用项目级 MCP」并确认；另注意 command 不能含空格，参数放 args
Trae依据：第三方实测
Gemini CLI 在未受信任目录下装不了 MCP server实测影响 258 条结论
- 什么时候会遇到
- 在未 trust 的目录里执行 mcp add，写项目级配置
- 你会看到什么
- Error: Cannot modify settings in an untrusted workspace —— 直接失败，不是配置写错
- 怎么解决
- 执行 gemini trust；自动化场景设 GEMINI_CLI_TRUST_WORKSPACE=true
Gemini CLI依据：本站实测
WorkBuddy 新配置不会自动生效，要手动 Trust实测影响 48 条结论
- 什么时候会遇到
- 刚编辑完 ~/.workbuddy/mcp.json
- 你会看到什么
- 配置文件正确，但会话里用不到工具
- 怎么解决
- 连接器管理页找到该条目点 Trust / 启用，然后重启会话
WBWorkBuddy依据：官方文档
Claude Code 项目级 server 需要人工批准实测影响 147 条结论
- 什么时候会遇到
- 通过 .mcp.json 加入项目级 server
- 你会看到什么
- add 成功但会话里不可用，等待批准
- 怎么解决
- 首次使用时批准；自动化场景改用 user scope 或 claude mcp add 后显式确认
Claude Code依据：官方文档