---
title: "MCP 集成"
description: "按官方文档整理 Windsurf MCP Marketplace、mcp_config.json、HTTP/SSE、认证插值、100 tools 限制和企业 registry。"
verifiedAt: "2026-05-09"
---

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

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

> [!TIP]
> **阅读目标**：读完本章，你应该能手动配置一个低风险 MCP，并知道为什么生产团队要用 registry、whitelist 和细粒度权限。

## 1. 添加 MCP 的三条路径

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

| 路径 | 入口 | 适合场景 |
| --- | --- | --- |
| Marketplace | Cascade 面板右上角 `MCPs` 图标，或 `Windsurf Settings > Cascade > MCP Servers` | 官方或常见 server，想快速安装 |
| Deeplink | `windsurf://windsurf-mcp-registry?serverName=<server-name>` | 文档里分享推荐 server，或一键打开 registry 页面 |
| 手动配置 | 编辑 `~/.codeium/windsurf/mcp_config.json` | 自建 server、内部 API、本地 stdio server |

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

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

```mermaid
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 基础结构

手动配置文件在：

```bash
~/.codeium/windsurf/mcp_config.json
```

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

```json
{
  "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。

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

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

| Transport | 适合场景 | 主要风险 |
| --- | --- | --- |
| `stdio` | 本机脚本、本地 CLI、Docker 容器 | 本机权限过大、依赖版本漂移 |
| Streamable HTTP | 远程受控服务、团队共享工具 | 认证、网络、审计和超时处理 |
| SSE | 需要持续事件流的旧式或兼容 server | 长连接、代理和重连策略 |

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

## 4. 不要把密钥写死

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

支持两种模式：

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

使用建议：

| 场景 | 推荐写法 | 原因 |
| --- | --- | --- |
| 本机 token | `${env:GITHUB_TOKEN}` | 不把 token 写进 JSON |
| 本机长期 secret | `${file:~/.secrets/api_key.txt}` | 可通过文件权限管理 |
| 团队共享配置 | 只保留变量名 | 每个人用自己的 secret 注入 |
| CI 或远程环境 | 短期 token / OAuth | 更容易撤权和审计 |

> [!WARNING]
> **不要把 `<YOUR_PERSONAL_ACCESS_TOKEN>` 替换成真实 token 后提交**。教程、仓库、截图和终端日志都不应该包含真实认证值。

## 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、数组长度都要匹配。

<details>
<summary>深读：为什么 registry 比复制配置更适合团队</summary>

复制 `mcp_config.json` 的问题是来源不可控：有人从 Marketplace 装，有人从 GitHub README 复制，有人改了 Docker image，有人硬编码 token。最后团队很难回答“这个 server 是否还被维护、是否扩大了权限、谁负责升级”。

Registry 的价值是把允许使用的 server、版本来源、认证方式和维护责任集中管理。Whitelist 则是安全闸门：一旦开始使用 whitelist，非白名单 server 会被阻止，适合对生产数据和内部系统做最小授权。
</details>

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

| 字段 | 需要写清 |
| --- | --- |
| Server ID | 必须和配置 key 匹配，注意大小写 |
| Transport | `stdio` / HTTP / SSE |
| Tools | 默认启用哪些，哪些必须关闭 |
| Auth | env、file、OAuth 或企业凭据系统 |
| Data boundary | 会读取哪些仓库、数据库、文件或 API |
| Write boundary | 是否能创建、更新、删除、发布或付款 |
| Owner | 谁负责升级、撤权、排障和审计 |

## 6. 商业项目接入顺序

推荐按风险分三阶段：

| 阶段 | 接入对象 | 验收标准 |
| --- | --- | --- |
| 第一阶段 | issue、文档、只读知识库、只读数据库 schema、监控摘要 | 能减少复制上下文，不写入生产系统 |
| 第二阶段 | 带写入能力的内部工具 | 权限拆细、人工确认、审计日志可回放 |
| 第三阶段 | 团队 registry、whitelist、OAuth、撤权流程 | 成员离职、token 失效、server 超时都有处理路径 |

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

## 7. 排障先分类

| 现象 | 优先检查 |
| --- | --- |
| server 不出现 | JSON 结构、key name、路径、command、args |
| server 出现但调用失败 | env/file 插值、token 作用域、过期时间、网络 |
| tools 太多或不相关 | MCP settings 的 tool toggles，是否超过 100 tools |
| whitelist 后被阻止 | Server ID 大小写、regex full match、args 数量 |
| HTTP server 失败 | `serverUrl` / `url`、HTTPS endpoint、headers、OAuth |

不要一上来删除整个 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)](https://docs.windsurf.com/windsurf/cascade/mcp) —— 官方 MCP 文档，覆盖 Marketplace、deeplink、tools toggle、`mcp_config.json`、HTTP MCP、插值、admin controls、registry 和 whitelist。
- [MCP Specification](https://modelcontextprotocol.io) —— 官方 MCP 协议入口，用于核对 transports、registry schema 和 server 规范。

## 接下来去哪

<Cards>
  <Card title="Skills 与 Workflows" description="继续判断什么时候写能力包，什么时候写手动流程，什么时候只写规则。" href="/docs/windsurf/official/05-skills-workflows" />
  <Card title="模型、用量与额度" description="继续核对模型选择、用量、quota 和 pricing 这类高波动事实。" href="/docs/windsurf/official/06-models-usage" />
</Cards>
