> ## 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.

# Model Context Protocol (MCP)

> 将 MCP 服务器与 Cascade 集成，以访问 GitHub、数据库和 API 等自定义工具。为 Teams 配置 stdio、HTTP 和 SSE 传输协议，并提供管理控制能力。

**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">
  ## 添加新的 MCP（模型上下文协议，Model Context Protocol）
</div>

可以通过 MCP Marketplace 添加新的 MCP，可在 Cascade 面板右上角菜单中点击 `MCPs` 图标进入，也可以在 `Windsurf Settings` > `Cascade` > `MCP Servers` 中进入。

如果找不到想要的 MCP，可以通过编辑原始的 `mcp_config.json` 文件手动添加。

官方 MCP 会显示一个蓝色对勾标记，表明它们由对应服务的官方公司提供。

当你点击某个 MCP 时，只需点击 `Install`，即可让 Cascade 访问该服务器及其工具。

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

Windsurf 也为每种传输类型提供 OAuth 支持。

对于 `http` 服务器，URL 应与其端点一致，并类似于 `https://<your-server-url>/mcp`。

<Frame>
  <img src="https://mintcdn.com/codeium/Rm_zdSOuabDsfa9L/assets/windsurf/cascade/mcp/mcp-plugin-store.png?fit=max&auto=format&n=Rm_zdSOuabDsfa9L&q=85&s=1f6f2165d7017097ebb08cba65d43362" width="955" height="774" data-path="assets/windsurf/cascade/mcp/mcp-plugin-store.png" />
</Frame>

<div id="configuring-mcp-tools">
  ## 配置 MCP 工具
</div>

每个 MCP 都可使用一定数量的工具。Cascade 在任意时间最多可访问 100 个工具。

在每个 MCP 的设置页面，你可以开关想要启用的工具。要打开某个 MCP 的设置，请点击 Cascade 面板右上角菜单中的 `MCPs` 图标，然后选择对应的 MCP。

<Frame>
  <img src="https://mintcdn.com/codeium/Rm_zdSOuabDsfa9L/assets/windsurf/cascade/mcp/mcp-manage-plugin-tools.png?fit=max&auto=format&n=Rm_zdSOuabDsfa9L&q=85&s=167fd87ffb6cf42228f6e62ff8cb6596" width="893" height="639" data-path="assets/windsurf/cascade/mcp/mcp-manage-plugin-tools.png" />
</Frame>

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

`~/.codeium/windsurf/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="popular-mcp-server-examples">
  ### 常用 MCP 服务器示例
</div>

以下是几个常用 MCP（模型上下文协议，Model Context Protocol）服务器的配置示例。可以将这些配置添加到 `mcp_config.json` 文件中。

<AccordionGroup>
  <Accordion title="GitHub" description="代码仓库管理、文件操作以及 GitHub API 集成。">
    GitHub MCP（模型上下文协议，Model Context Protocol）服务器提供仓库管理、文件操作、Issue 跟踪以及拉取请求（Pull Request）管理等工具。

    **使用 npx：**

    ```json theme={null}
    {
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
          }
        }
      }
    }
    ```

    **使用 Docker：**

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

    要创建个人访问令牌（Personal Access Token），请访问 [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)。
  </Accordion>

  <Accordion title="Slack" description="用于 Slack 工作区的频道管理和消息功能。">
    Slack MCP 服务器支持频道管理、消息收发以及与工作区的交互。

    ```json theme={null}
    {
      "mcpServers": {
        "slack": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-slack"],
          "env": {
            "SLACK_BOT_TOKEN": "<YOUR_SLACK_BOT_TOKEN>",
            "SLACK_TEAM_ID": "<YOUR_SLACK_TEAM_ID>"
          }
        }
      }
    }
    ```

    设置 Slack 机器人令牌的步骤：

    1. 在 [api.slack.com/apps](https://api.slack.com/apps) 创建一个 Slack App
    2. 添加所需的 OAuth 权限范围（例如 `channels:read`、`chat:write`、`users:read`）
    3. 将应用安装到你的工作区，并复制 Bot User OAuth Token
  </Accordion>

  <Accordion title="PostgreSQL" description="具备模式检查能力的只读数据库访问。">
    PostgreSQL MCP 服务器为 PostgreSQL 数据库提供只读访问，包括模式（schema）检查和查询执行。

    ```json theme={null}
    {
      "mcpServers": {
        "postgres": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres"],
          "env": {
            "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
          }
        }
      }
    }
    ```

    <Warning>出于安全考虑，PostgreSQL 服务器默认只提供只读访问。请确保你的连接字符串使用具有受限权限的适当凭据。</Warning>
  </Accordion>

  <Accordion title="Filesystem" description="具有可配置访问控制的安全文件操作。">
    Filesystem MCP 服务器为本地文件和目录提供安全访问，并支持可配置的访问控制。

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y", "@modelcontextprotocol/server-filesystem",
            "/path/to/allowed/directory"
          ]
        }
      }
    }
    ```

    你可以通过添加额外的路径参数来指定多个允许访问的目录。只有这些目录中的文件才会被访问。
  </Accordion>

  <Accordion title="Brave Search" description="使用 Brave 的 Search API 进行网页与本地搜索。">
    Brave Search MCP 服务器通过 Brave Search API 提供网页搜索能力。

    ```json theme={null}
    {
      "mcpServers": {
        "brave-search": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>"
          }
        }
      }
    }
    ```

    如需获取 Brave API key，请在 [brave.com/search/api](https://brave.com/search/api/) 注册。
  </Accordion>

  <Accordion title="Memory" description="基于知识图谱的持久化记忆系统。">
    Memory MCP 服务器通过知识图谱提供持久化记忆系统，使 Cascade 能够在不同会话之间记住信息。

    ```json theme={null}
    {
      "mcpServers": {
        "memory": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-memory"]
        }
      }
    }
    ```

    Memory 服务器会在本地存储数据，并在会话之间保持持久化，非常适合用于维护关于项目、偏好和已学习信息的上下文。
  </Accordion>
</AccordionGroup>

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

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

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

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

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

`~/.codeium/windsurf/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 和 Enterprise）
</div>

团队管理员可以为其团队开启或关闭 MCP 访问，并为团队配置允许使用的 MCP 服务器白名单：

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

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

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

<Note>白名单中的 Server ID 必须与用户 `mcp_config.json` 中使用的键名完全一致，且大小写需完全匹配。</Note>

<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"
          }
        }
      }
    }
    ```

    这样，只要 Server ID 与插件商店条目一致，用户即可使用任意有效配置安装 GitHub MCP 服务器。
  </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 服务器的[工具](https://modelcontextprotocol.io/docs/concepts/tools)、[资源](https://modelcontextprotocol.io/docs/concepts/resources)和[提示](https://modelcontextprotocol.io/docs/concepts/prompts)。