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

# 模型上下文协议（MCP）

> 配置 MCP 服务器，使用 stdio、HTTP 或 SSE 传输，为 Cascade 添加自定义工具和服务，并支持针对 Teams 和 Enterprise 的 Admin 控制。

\*\*MCP (模型上下文协议) \*\*是一种让 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/cognitionai/-PTA3zzo2bR9Qfc8/desktop/assets/plugins/mcp-server-templates.jpg?fit=max&auto=format&n=-PTA3zzo2bR9Qfc8&q=85&s=011ca9d571dfa249d10d9f34b7287642" width="1666" height="1388" data-path="desktop/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": "<YOUR_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

请务必为你要使用的服务器提供必填参数和环境变量。

你可以参考 [官方 MCP 服务器参考代码仓库](https://github.com/modelcontextprotocol/servers) 或 [OpenTools](https://opentools.com/)，查看一些示例服务器。

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

需要注意的是，远程 HTTP MCP 的配置略有不同，
需要使用 `serverUrl` 或 `url` 字段。

以下是 HTTP server 的配置示例：

```json theme={null}
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/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">
  ## Admin 控制 (团队和企业)
</div>

团队 Admin 可以为团队开启或关闭 MCP 访问权限，也可以将已批准的 MCP 服务器加入白名单，供团队使用：

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

<Warning>只有当你拥有团队 Admin 权限时，上述链接才可用。</Warning>

默认情况下，团队中的用户可以配置自己的 MCP 服务器。不过，一旦你将哪怕一个 MCP 服务器加入白名单，**所有未列入白名单的服务器都会被团队屏蔽**。

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

当你将某个 MCP 服务器加入白名单时，系统会按以下规则使用**正则表达式模式匹配**：

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

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

<AccordionGroup>
  <Accordion title="选项 1：插件商店默认配置（推荐）" description="将“服务器配置（JSON）”字段留空，即可使用 Windsurf MCP Plugin Store 中的默认配置。">
    **Admin 白名单配置：**

    * **服务器 ID**: `github-mcp-server`
    * **服务器配置 (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"
          }
        }
      }
    }
    ```

    这样一来，只要服务器 ID 与插件商店中的条目匹配，用户就可以使用任何有效配置来安装 GitHub MCP 服务器。
  </Accordion>

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

    * **服务器 ID**: `github-mcp-server`
    * **服务器配置 (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="使用正则表达式模式，在保持安全控制的同时允许用户配置存在一定变化。">
    **Admin 白名单配置：**

    * **服务器 ID**: `python-mcp-server`
    * **服务器配置 (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">
  ### Admin 配置指南
</div>

* **环境变量**：`env` 部分不进行正则匹配，用户可自由配置
* **已禁用的工具**：`disabledTools` 数组会单独处理，不属于白名单匹配范围
* **区分大小写**：所有匹配均区分大小写
* **错误处理**：无效的正则表达式模式会被记录，并导致访问被拒绝
* **测试**：请仔细测试你的正则表达式模式——限制过严的模式可能会拦截正常使用场景

<div id="troubleshooting">
  ### 故障排查
</div>

如果用户反馈其 MCP 服务器在加入白名单后无法正常工作：

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

请记住：只要你将任意服务器加入白名单，**所有其他服务器都会自动被阻止**，你的团队成员将无法使用它们。

<div id="general-information">
  ### 一般信息
</div>

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