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

# Model Context Protocol (MCP)

> 将 MCP 服务器与 Cascade 集成，访问 GitHub、数据库和 API 等自定义工具。通过 Teams 的 Admin 控制配置 stdio、HTTP 和 SSE 传输。

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

<Note>企业版用户必须通过设置手动开启此功能</Note>

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

你可以通过 MCP Marketplace 添加新的 MCP。进入方式包括：点击 Cascade 面板右上角菜单中的 `MCPs` 图标，或前往 `Devin Settings` > `Cascade` > `MCP Servers` 部分。

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

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

点击某个 MCP 后，只需点击 `Install`，即可将该 MCP 服务器及其工具提供给 Cascade 使用。

<div id="one-click-install-via-deeplink">
  ### 通过 Deeplink 一键安装
</div>

Devin Desktop 支持通过 deeplink 一键安装 MCP。你可以使用这些链接直接在 Devin Desktop 中打开 MCP
注册表页面，这非常适合分享 MCP 服务器推荐，或在文档中嵌入安装按钮。

deeplink 格式如下：

```
windsurf://windsurf-mcp-registry?serverName=<server-name>
```

* **使用 `serverName`**：打开指定服务器的 MCP 注册表页面，用户可以在其中查看并安装该服务器。
* **不使用 `serverName`**：打开 MCP Marketplace 页面。

例如，`windsurf://windsurf-mcp-registry?serverName=github-mcp-server` 会在 Devin Desktop 中打开 GitHub MCP 服务器的注册表页面。

<Note>一键安装深度链接要求用户所在团队已启用 MCP 访问权限。如果 MCP 访问已被 Admin 禁用，该深度链接将无法打开注册表页面。</Note>

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

Devin Desktop 还支持为每种传输类型使用 OAuth。

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

<Frame>
  <img src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/mcp/mcp-plugin-store.png?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=cedf7260fa823c72486f1c35faa542f0" width="955" height="774" data-path="desktop/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/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/mcp/mcp-manage-plugin-tools.png?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=81513e7073b00eb6d9c53017789b08c1" width="893" height="639" data-path="desktop/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": "<YOUR_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}
```

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

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

<div id="popular-mcp-server-examples">
  ### 常见 MCP 服务器示例
</div>

下面列出了一些常用 MCP 服务器的配置示例。你可以将它们添加到 `mcp_config.json` 文件中。

<AccordionGroup>
  <Accordion title="GitHub" description="代码仓库管理、文件操作和 GitHub API 集成。">
    GitHub MCP 服务器提供用于代码仓库管理、文件操作、issue 跟踪和拉取请求管理的工具。

    **使用 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>"
          }
        }
      }
    }
    ```

    要创建个人访问令牌，请访问 [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 bot 令牌：

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

  <Accordion title="PostgreSQL" description="具有架构检查功能的只读数据库访问。">
    PostgreSQL MCP 服务器提供对 PostgreSQL 数据库的只读访问，包括架构检查和查询执行。

    ```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`。这样你就可以避免在配置文件中直接硬编码 secrets。

支持以下两种插值模式：

* **`${env:VAR_NAME}`** — 替换为环境变量 `VAR_NAME` 的值。如果该变量未设置，则会解析为空字符串。
* **`${file:/path/to/file}`** — 替换为指定路径下文件内容去除首尾空白后的结果。支持波浪号路径 (例如 `~/secrets/key.txt`) 。如果无法读取文件，则保留该模式字符串不变。

下面是一个在 `headers` 中使用环境变量的示例：

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

以下是一个从文件中读取 API key 的示例：

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${file:~/.secrets/api_key.txt}"
      }
    }
  }
}
```

<div id="admin-controls-teams-enterprises">
  ## Admin 控制 (团队和企业)
</div>

团队管理员可以为团队启用或禁用 MCP 访问权限，也可以将经批准的 MCP 服务器加入白名单，供团队使用：

<div id="mcp-registry">
  ### MCP Registry
</div>

企业团队可以配置自定义 MCP 注册表，以替代默认的 Devin Desktop MCP Marketplace。团队可以关联自己的注册表 URL，以控制其用户可使用哪些 MCP。

<Note>注册表是管理 MCP 访问权限的首选方式，不过白名单也同样适用。</Note>

<div id="configuring-custom-registries">
  #### 配置自定义注册表
</div>

1. 前往团队设置
2. 找到 **MCP Registry URLs** 设置
3. 添加一个或多个注册表 URL

配置了多个注册表 URL 后，Devin Desktop 会将所有注册表取**并集**——用户将看到来自所有已配置来源的 MCP 汇总结果。随后，团队的 MCP marketplace 将从这些内部注册表拉取内容，而不是默认的 Devin Desktop 注册表。

<Note>自定义注册表必须遵循[官方 MCP 注册表架构](https://modelcontextprotocol.io/)。这可确保兼容性以及标准化的服务器定义。</Note>

<div id="mcp-whitelist">
  ### MCP 白名单
</div>

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

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

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

<Note>白名单中的服务器 ID 必须与用户 `mcp_config.json` 中使用的键名完全匹配，且区分大小写。</Note>

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

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

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

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

<AccordionGroup>
  <Accordion title="选项 1：插件商店默认配置（推荐）" description="将 Server Config (JSON) 字段留空，即可使用 Devin Desktop 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"
          }
        }
      }
    }
    ```

    这允许用户安装 GitHub MCP 服务器并使用任意有效配置，只要服务器 ID 与插件商店中的条目一致即可。
  </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>

| Pattern         | Matches     | Example                |
| --------------- | ----------- | ---------------------- |
| `.*`            | 任意字符串       | `/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)。