MCP 集成

MCP（Model Context Protocol，模型上下文协议） 是把 Cascade 接到外部工具和服务的协议层。可以把它理解成”AI 工具的 USB 接口标准”——定一套统一的协议，任何外部系统（GitHub / 数据库 / 内部 API / 工单 / 浏览器等）按这套协议接进来，Cascade 就能用同一种方式调用。Windsurf 官方文档明确说，Cascade 作为 MCP client（客户端），可以请求 MCP servers（服务端）暴露的 tools；常见场景包括 GitHub、数据库、API 和内部系统。

这意味着 MCP 不是”更多插件”，而是外部系统权限入口。接入前先问：这个 server 能读什么、能写什么、谁维护、怎么认证、怎么撤权、失败时是否会重复调用。

1. 添加 MCP 的三条路径

官方文档给出几种添加方式：

官方 MCP 会显示蓝色 checkmark，表示由对应母服务公司制作。这个标记只能说明来源，不等于它适合你的权限边界。

Enterprise 用户还要先确认管理员是否开启 MCP access。官方说明如果团队关闭了 MCP access，即使使用 one-click deeplink，也不会打开对应 registry 页面。

flowchart TD
    Need["需要外部系统能力"] --> Read{"只读还是写入?"}
    Read -->|只读| Market["优先 Marketplace / registry"]
    Read -->|写入| Scope["拆分权限和工具名"]
    Market --> Config["检查 mcp_config.json / tools 开关"]
    Scope --> Config
    Config --> Auth["用 env/file/OAuth 管理认证"]
    Auth --> Limit["控制 tools 数量和可用范围"]
    Limit --> Team{"团队使用?"}
    Team -->|是| Registry["registry + whitelist + admin controls"]
    Team -->|否| Local["本机配置 + 手动审查"]

    style Auth fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Registry fill:#dbeafe,stroke:#2563eb,stroke-width:2px

2. 先控制 tools 数量

官方文档说明，每个 MCP 有一组 tools；Cascade 同一时间可访问的 tools 总数上限是 100。你可以在每个 MCP settings 页面里切换要启用的 tools。

这个限制很实际。不要把一个大而全的 server 全部打开，尤其是带写入能力的 server。更稳的做法：

• 先启用只读 tools。
• 禁用删除、发布、付款、权限变更、批量导出。
• 为高风险动作单独建 server 或单独工具名。
• 让 Cascade 调用前能清楚说出 tool 名和参数。

3. mcp_config.json 基础结构

手动配置文件在：

~/.codeium/windsurf/mcp_config.json

基础结构是 mcpServers。stdio server 通常使用 command、args 和 env：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Remote HTTP MCP 要用 serverUrl 或 url。官方还说明 Windsurf 支持 stdio、Streamable HTTP 和 SSE 三种 transport，并支持每种 transport 的 OAuth；HTTP server 的 URL 应指向类似 https://<your-server-url>/mcp 的 endpoint。

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "https://example.internal/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

选择 transport 时按部署位置判断：

OAuth 适合团队级远程 server；本机 stdio server 更常见的是 env/file 插值。不要为了省配置把生产 token 写进 JSON。

4. 不要把密钥写死

官方文档说明 mcp_config.json 在这些字段支持变量插值：command、args、env、serverUrl、url、headers。

支持两种模式：

${env:VAR_NAME}
${file:/path/to/file}

使用建议：

5. 企业 registry 与 whitelist

Teams 和 Enterprise 管理员可以开关 MCP access，也可以维护 whitelist。官方文档说明，企业团队可以配置 custom MCP registries 替代默认 Windsurf MCP marketplace；registry 是管理 MCP access 的推荐方式，whitelist 也可用。

几个关键规则：

• 配置多个 registry URL 时，Windsurf 会取 union，用户看到所有 registry 合并后的 server。
• 一旦 whitelist 里加入任意 MCP server，非 whitelist server 会被团队阻止。
• whitelist 的 Server ID 必须和用户 mcp_config.json 里的 key name 区分大小写匹配。
• server matching 使用 regex full string matching，command、args、数组长度都要匹配。

上线前把每个 MCP server 记录成一张准入卡：

6. 商业项目接入顺序

推荐按风险分三阶段：

MCP 接入完成的标志不是“能调用成功”，而是失败、越权、超时、撤权和敏感字段返回时都有明确处理方式。

7. 排障先分类

不要一上来删除整个 Windsurf 配置目录。保留失败配置，复制一个最小 server 做对照，再逐项缩小问题范围。

最小化排障顺序：

1. 先禁用其他 MCP，只保留一个 server。
2. 把写入 tools 关掉，只测只读 tool。
3. 确认 env/file 插值能在当前 shell 中读到。
4. HTTP/SSE server 先用只读 health endpoint 验证网络和认证。
5. 再回到 Cascade 里测试 tool 调用。

本章自检

完成本章后，用这 4 个问题检查：

1. 你接入的是只读 MCP，还是带写入能力的 MCP？
2. mcp_config.json 是否没有硬编码真实 token？
3. 是否只启用了必要 tools，并知道 100 tools 总上限？
4. 团队是否需要 registry、whitelist 和撤权流程？

通过标准：你能把 MCP 从“能装上”推进到“权限可控、认证可撤、失败可排查”。

官方来源

• Model Context Protocol (MCP) —— 官方 MCP 文档，覆盖 Marketplace、deeplink、tools toggle、mcp_config.json、HTTP MCP、插值、admin controls、registry 和 whitelist。
• MCP Specification —— 官方 MCP 协议入口，用于核对 transports、registry schema 和 server 规范。

接下来去哪