> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型上下文协议（MCP，Model Context Protocol）

> 配置 MCP 服务器，为 Cascade 扩展自定义工具和服务，并通过 stdio、HTTP 或 SSE 作为传输方式，同时为 Teams 和 Enterprise 提供管理控制。

**MCP（模型上下文协议，Model Context Protocol）** 是一种协议，使 LLM 能够访问自定义工具和服务。
MCP 客户端（此处为 Cascade）可以向 MCP 服务器发起请求，以使用其提供的工具。
Cascade 现已原生集成 MCP，你可以接入自选的 MCP 服务器供 Cascade 使用。
更多信息请参阅[官方 MCP 文档](https://modelcontextprotocol.io/)。

<Note>Enterprise 用户需在设置中手动启用</Note>

<div id="adding-a-new-mcp-plugin">
  ## 添加新的 MCP 插件
</div>

可通过 `Settings` > `Tools` > `Windsurf Settings` > `Add Server` 添加新的 MCP 插件。

如果找不到目标 MCP 插件，可点击 `View Raw Config` 按钮并编辑原始 `mcp_config.json` 文件手动添加。

在选择某个 MCP 服务器后，点击 `+ Add Server`，即可将该服务器及其工具提供给 Cascade 使用。

<Frame>
  <img src="https://mintcdn.com/codeium/d8O4q6w3H2CjrirL/assets/plugins/mcp-server-templates.jpg?fit=max&auto=format&n=d8O4q6w3H2CjrirL&q=85&s=06f96424bd8374333d6969006868456e" width="1666" height="1388" data-path="assets/plugins/mcp-server-templates.jpg" />
</Frame>

Cascade 支持 MCP 服务器的三种[传输类型](https://modelcontextprotocol.io/docs/concepts/transports)：`stdio`、`Streamable HTTP` 和 `SSE`。

Cascade 还支持在每种传输类型中使用 OAuth 认证。

对于 `http` 服务器，URL 应指向相应的端点，形如 `https://<your-server-url>/mcp`。

<Note>添加新的 MCP 插件后，请务必点击刷新按钮。</Note>

<div id="mcp_configjson">
  ## mcp\_config.json
</div>

`~/.codeium/mcp_config.json` 文件是一个 JSON 文件，包含 Cascade 可连接的服务器列表。

下面是一个示例配置，用于设置一个 GitHub 服务器：

```json theme={null}
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<您的个人访问令牌>"
      }
    }
  }
}
```

请确保为你要使用的服务器提供所需的参数和环境变量。

请参阅[官方 MCP 服务器参考仓库](https://github.com/modelcontextprotocol/servers)或 [OpenTools](https://opentools.com/)，以获取示例服务器。

<div id="remote-http-mcps">
  ### 远程 HTTP MCP
</div>

需要注意的是，对于远程 HTTP 类型的 MCP（模型上下文协议，Model Context Protocol）服务器，配置略有不同，并且需要包含一个 `serverUrl` 或 `url` 字段。

下面是一个 HTTP 服务器的示例配置：

```json theme={null}
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<您的服务器地址>/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}
```

<div id="config-interpolation">
  ### 配置插值
</div>

`~/.codeium/mcp_config.json` 文件会在以下字段中对环境变量进行插值展开：`command`、`args`、`env`、`serverUrl`、`url` 和 `headers`。

下面是一个示例配置，在 `headers` 中使用了 `AUTH_TOKEN` 环境变量。

```json theme={null}
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}
```

<div id="admin-controls-teams-enterprises">
  ## 管理控制（Teams & Enterprises）
</div>

团队管理员可以为其团队启用或停用 MCP 访问，并将已批准的 MCP 服务器加入白名单供团队使用：

<Card title="MCP 团队设置" horizontal={true} icon="hammer" href="https://windsurf.com/team/settings">
  为你的团队配置 MCP 相关设置。
</Card>

<Warning>只有当你在团队中拥有管理员权限时，上述链接才会生效。</Warning>

默认情况下，团队内的用户可以配置自己的 MCP 服务器。但是，一旦你将哪怕一个 MCP 服务器加入白名单，**所有未被加入白名单的服务器都会被阻止**，团队成员将无法使用。

<div id="how-server-matching-works">
  ### 服务器匹配原理
</div>

当你将某个 MCP（模型上下文协议，Model Context Protocol）服务器加入白名单时，系统会使用**正则表达式模式匹配**，并遵循以下规则：

* **完整字符串匹配**：所有模式会自动加锚点（使用 `^(?:pattern)$` 包裹）以避免部分匹配
* **Command 字段**：必须精确匹配，或符合你的正则表达式模式
* **Arguments 数组**：每个参数都会分别与其对应的模式进行匹配
* **数组长度**：白名单与用户配置的参数数量必须完全一致
* **特殊字符**：如 `$`、`.`、`[`、`]`、`(`、`)` 等字符在正则中具有特殊含义，如需按字面匹配，应使用 `\` 进行转义

<div id="configuration-options">
  ### 配置选项
</div>

<AccordionGroup>
  <Accordion title="选项 1：插件商店默认（推荐）" description="将 Server Config（JSON）字段留空，以使用来自 Windsurf MCP Plugin Store 的默认配置。">
    **管理员白名单配置：**

    * **Server ID**: `github-mcp-server`
    * **Server Config（JSON）**: *(留空)*

    ```json theme={null}
    {}
    ```

    **对应的用户配置（`mcp_config.json`）：**

    ```json theme={null}
    {
      "mcpServers": {
        "github-mcp-server": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_PERSONAL_ACCESS_TOKEN",
            "ghcr.io/github/github-mcp-server"
          ],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
          }
        }
      }
    }
    ```

    这允许用户安装 GitHub MCP 服务器，并使用任意有效配置，只要该 Server ID 与插件商店条目一致即可。
  </Accordion>

  <Accordion title="选项 2：精确匹配配置" description="提供用户必须使用的精确配置。用户必须与此配置完全一致。">
    **管理员白名单配置：**

    * **Server ID**: `github-mcp-server`
    * **Server Config（JSON）**:

    ```json theme={null}
    {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    }
    ```

    **对应的用户配置（`mcp_config.json`）：**

    ```json theme={null}
    {
      "mcpServers": {
        "github-mcp-server": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_PERSONAL_ACCESS_TOKEN",
            "ghcr.io/github/github-mcp-server"
          ],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
          }
        }
      }
    }
    ```

    用户必须使用此完全一致的配置——对 `command` 或 `args` 的任何改动都会被阻止。`env` 部分的取值可以不同。
  </Accordion>

  <Accordion title="选项 3：灵活的正则表达式模式" description="使用正则表达式，在保持安全控制的同时允许用户配置存在变体。">
    **管理员白名单配置：**

    * **Server ID**: `python-mcp-server`
    * **Server Config（JSON）**:

    ```json theme={null}
    {
      "command": "python3",
      "args": ["/.*\\.py", "--port", "[0-9]+"]
    }
    ```

    **对应的用户配置（`mcp_config.json`）：**

    ```json theme={null}
    {
      "mcpServers": {
        "python-mcp-server": {
          "command": "python3",
          "args": ["/home/user/my_server.py", "--port", "8080"],
          "env": {
            "PYTHONPATH": "/home/user/mcp"
          }
        }
      }
    }
    ```

    此示例在保持安全性的同时为用户提供灵活性：

    * 正则 `/.*\\.py` 匹配任意 Python 文件路径，如 `/home/user/my_server.py`
    * 正则 `[0-9]+` 匹配任意数字端口，如 `8080` 或 `3000`
    * 用户可自定义文件路径和端口，管理员则可确保仅执行 Python 脚本
  </Accordion>
</AccordionGroup>

<div id="common-regex-patterns">
  ### 常见正则表达式模式
</div>

| 模式              | 匹配项         | 示例                     |
| --------------- | ----------- | ---------------------- |
| `.*`            | 任意字符串       | `/home/user/script.py` |
| `[0-9]+`        | 任意数字        | `8080`, `3000`         |
| `[a-zA-Z0-9_]+` | 字母数字与下划线    | `api_key_123`          |
| `\\$HOME`       | 字面量 `$HOME` | `$HOME`（不会展开）          |
| `\\.py`         | 字面量 `.py`   | `script.py`            |
| `\\[cli\\]`     | 字面量 `[cli]` | `mcp[cli]`             |

<div id="notes">
  ## 说明
</div>

<div id="admin-configuration-guidelines">
  ### 管理员配置指南
</div>

* **环境变量**：`env` 部分不进行正则匹配，用户可自由配置
* **禁用工具**：`disabledTools` 数组单独处理，不参与白名单匹配
* **区分大小写**：所有匹配均区分大小写
* **错误处理**：无效的正则表达式会被记录，并导致拒绝访问
* **测试**：请仔细测试你的正则表达式——过于严格的规则可能会阻断合法用例

<div id="troubleshooting">
  ### 疑难解答
</div>

如果用户在加入白名单后仍报告其 MCP（模型上下文协议，Model Context Protocol）服务器无法工作：

1. **检查精确匹配**：确保白名单模式与用户的实际配置完全一致
2. **确认正则转义**：特殊字符可能需要转义（例如，将点作为字面量时使用 `\.`）
3. **查看日志**：无效的正则模式会以警告的形式记录在日志中
4. **测试模式**：使用正则测试工具验证模式是否按预期工作

请记住：一旦你将任何服务器加入白名单，**其他所有服务器都会自动对你的团队成员被阻止**。

<div id="general-information">
  ### 通用信息
</div>

* 由于 MCP 工具调用可能会执行由任意服务器实现者编写的代码，我们不对 MCP 工具调用失败承担责任。再次说明：
* 我们目前支持 MCP 服务器的 [tools](https://modelcontextprotocol.io/docs/concepts/tools)、[resources](https://modelcontextprotocol.io/docs/concepts/resources) 和 [prompts](https://modelcontextprotocol.io/docs/concepts/prompts)。