跳转到主要内容

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） 是一种协议，使 LLM 能够访问自定义工具和服务。 MCP 客户端（此处为 Cascade）可以向 MCP 服务器发起请求，以使用其提供的工具。 Cascade 现已原生集成 MCP，你可以接入自选的 MCP 服务器供 Cascade 使用。 更多信息请参阅官方 MCP 文档。
Enterprise 用户需在设置中手动启用

​
添加新的 MCP 插件

可通过 Settings > Tools > Windsurf Settings > Add Server 添加新的 MCP 插件。 如果找不到目标 MCP 插件，可点击 View Raw Config 按钮并编辑原始 mcp_config.json 文件手动添加。 在选择某个 MCP 服务器后，点击 + Add Server，即可将该服务器及其工具提供给 Cascade 使用。
Cascade 支持 MCP 服务器的三种传输类型：stdio、Streamable HTTP 和 SSE。 Cascade 还支持在每种传输类型中使用 OAuth 认证。 对于 http 服务器，URL 应指向相应的端点，形如 https://<your-server-url>/mcp。
添加新的 MCP 插件后，请务必点击刷新按钮。

​
mcp_config.json

~/.codeium/mcp_config.json 文件是一个 JSON 文件，包含 Cascade 可连接的服务器列表。 下面是一个示例配置，用于设置一个 GitHub 服务器： 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<您的个人访问令牌>"
      }
    }
  }
}
请确保为你要使用的服务器提供所需的参数和环境变量。 请参阅官方 MCP 服务器参考仓库或 OpenTools，以获取示例服务器。

​
远程 HTTP MCP

需要注意的是，对于远程 HTTP 类型的 MCP（模型上下文协议，Model Context Protocol）服务器，配置略有不同，并且需要包含一个 serverUrl 或 url 字段。 下面是一个 HTTP 服务器的示例配置： 
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<您的服务器地址>/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

​
配置插值

~/.codeium/mcp_config.json 文件会在以下字段中对环境变量进行插值展开：command、args、env、serverUrl、url 和 headers。 下面是一个示例配置，在 headers 中使用了 AUTH_TOKEN 环境变量。 
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

​
管理控制（Teams & Enterprises）

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

MCP 团队设置

为你的团队配置 MCP 相关设置。
只有当你在团队中拥有管理员权限时，上述链接才会生效。
默认情况下，团队内的用户可以配置自己的 MCP 服务器。但是，一旦你将哪怕一个 MCP 服务器加入白名单，所有未被加入白名单的服务器都会被阻止，团队成员将无法使用。

​
服务器匹配原理

当你将某个 MCP（模型上下文协议，Model Context Protocol）服务器加入白名单时，系统会使用正则表达式模式匹配，并遵循以下规则：
  • 完整字符串匹配：所有模式会自动加锚点（使用 ^(?:pattern)$ 包裹）以避免部分匹配
  • Command 字段：必须精确匹配，或符合你的正则表达式模式
  • Arguments 数组：每个参数都会分别与其对应的模式进行匹配
  • 数组长度：白名单与用户配置的参数数量必须完全一致
  • 特殊字符：如 $、.、[、]、(、) 等字符在正则中具有特殊含义，如需按字面匹配，应使用 \ 进行转义

​
配置选项

管理员白名单配置：
  • Server ID: github-mcp-server
  • Server Config（JSON）: (留空)
{}
对应的用户配置（mcp_config.json）：
{
  "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 与插件商店条目一致即可。
管理员白名单配置：
  • Server ID: github-mcp-server
  • Server Config（JSON）:
{
  "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）：
{
  "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 部分的取值可以不同。
管理员白名单配置：
  • Server ID: python-mcp-server
  • Server Config（JSON）:
{
  "command": "python3",
  "args": ["/.*\\.py", "--port", "[0-9]+"]
}
对应的用户配置（mcp_config.json）：
{
  "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 脚本

​
常见正则表达式模式

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

​
说明

​
管理员配置指南

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

​
疑难解答

如果用户在加入白名单后仍报告其 MCP（模型上下文协议，Model Context Protocol）服务器无法工作：
  1. 检查精确匹配：确保白名单模式与用户的实际配置完全一致
  2. 确认正则转义：特殊字符可能需要转义（例如，将点作为字面量时使用 \.）
  3. 查看日志：无效的正则模式会以警告的形式记录在日志中
  4. 测试模式：使用正则测试工具验证模式是否按预期工作
请记住：一旦你将任何服务器加入白名单，其他所有服务器都会自动对你的团队成员被阻止。

​
通用信息

  • 由于 MCP 工具调用可能会执行由任意服务器实现者编写的代码，我们不对 MCP 工具调用失败承担责任。再次说明：
  • 我们目前支持 MCP 服务器的 tools、resources 和 prompts。