---
title: "MCP 整合"
description: "按官方文件整理 Windsurf MCP Marketplace、mcp_config.json、HTTP/SSE、認證插值、100 tools 限制和企業 registry。"
verifiedAt: "2026-05-09"
---

**MCP（Model Context Protocol，模型上下文協議）** 是把 Cascade 接到外部工具和服務的協議層。可以把它理解成”AI 工具的 USB 介面標準”——定一套統一的協議，任何外部系統（GitHub / 資料庫 / 內部 API / 工單 / 瀏覽器等）按這套協議接進來，Cascade 就能用同一種方式呼叫。Windsurf 官方文件明確說，Cascade 作為 MCP client（客戶端），可以請求 MCP servers（服務端）暴露的 tools；常見場景包括 GitHub、資料庫、API 和內部系統。

這意味著 MCP 不是”更多外掛”，而是外部系統許可權入口。接入前先問：這個 server 能讀什麼、能寫什麼、誰維護、怎麼認證、怎麼撤權、失敗時是否會重複呼叫。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能手動配置一個低風險 MCP，並知道為什麼生產團隊要用 registry、whitelist 和細粒度許可權。

## 1. 新增 MCP 的三條路徑

官方文件給出幾種新增方式：

| 路徑 | 入口 | 適合場景 |
| --- | --- | --- |
| Marketplace | Cascade 面板右上角 `MCPs` 圖示，或 `Windsurf Settings > Cascade > MCP Servers` | 官方或常見 server，想快速安裝 |
| Deeplink | `windsurf://windsurf-mcp-registry?serverName=<server-name>` | 文件裡分享推薦 server，或一鍵開啟 registry 頁面 |
| 手動配置 | 編輯 `~/.codeium/windsurf/mcp_config.json` | 自建 server、內部 API、本地 stdio server |

官方 MCP 會顯示藍色 checkmark，表示由對應母服務公司製作。這個標記只能說明來源，不等於它適合你的許可權邊界。

Enterprise 使用者還要先確認管理員是否開啟 MCP access。官方說明如果團隊關閉了 MCP access，即使使用 one-click deeplink，也不會開啟對應 registry 頁面。

```mermaid
flowchart TD
    Need["需要外部系統能力"] --> Read{"只讀還是寫入?"}
    Read -->|只讀| Market["優先 Marketplace / registry"]
    Read -->|寫入| Scope["拆分許可權和工具名"]
    Market --> Config["檢查 mcp_config.json / tools 開關"]
    Scope --> Config
    Config --> Auth["用 env/file/OAuth 管理認證"]
    Auth --> Limit["控制 tools 數量和可用範圍"]
    Limit --> Team{"團隊使用?"}
    Team -->|是| Registry["registry + whitelist + admin controls"]
    Team -->|否| Local["本機配置 + 手動審查"]

    style Auth fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Registry fill:#dbeafe,stroke:#2563eb,stroke-width:2px
```

## 2. 先控制 tools 數量

官方文件說明，每個 MCP 有一組 tools；Cascade 同一時間可訪問的 tools 總數上限是 100。你可以在每個 MCP settings 頁面裡切換要啟用的 tools。

這個限制很實際。不要把一個大而全的 server 全部開啟，尤其是帶寫入能力的 server。更穩的做法：

- 先啟用只讀 tools。
- 停用刪除、釋出、付款、許可權變更、批次匯出。
- 為高風險動作單獨建 server 或單獨工具名。
- 讓 Cascade 呼叫前能清楚說出 tool 名和引數。

## 3. mcp_config.json 基礎結構

手動配置檔案在：

```bash
~/.codeium/windsurf/mcp_config.json
```

基礎結構是 `mcpServers`。stdio server 通常使用 `command`、`args` 和 `env`：

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}
```

Remote HTTP MCP 要用 `serverUrl` 或 `url`。官方還說明 Windsurf 支援 `stdio`、`Streamable HTTP` 和 `SSE` 三種 transport，並支援每種 transport 的 OAuth；HTTP server 的 URL 應指向類似 `https://<your-server-url>/mcp` 的 endpoint。

```json
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "https://example.internal/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}
```

選擇 transport 時按部署位置判斷：

| Transport | 適合場景 | 主要風險 |
| --- | --- | --- |
| `stdio` | 本機指令碼、本地 CLI、Docker 容器 | 本機許可權過大、依賴版本漂移 |
| Streamable HTTP | 遠端受控服務、團隊共享工具 | 認證、網路、審計和超時處理 |
| SSE | 需要持續事件流的舊式或相容 server | 長連線、代理和重連策略 |

OAuth 適合團隊級遠端 server；本機 `stdio` server 更常見的是 env/file 插值。不要為了省配置把生產 token 寫進 JSON。

## 4. 不要把金鑰寫死

官方文件說明 `mcp_config.json` 在這些欄位支援變數插值：`command`、`args`、`env`、`serverUrl`、`url`、`headers`。

支援兩種模式：

```text
${env:VAR_NAME}
${file:/path/to/file}
```

使用建議：

| 場景 | 推薦寫法 | 原因 |
| --- | --- | --- |
| 本機 token | `${env:GITHUB_TOKEN}` | 不把 token 寫進 JSON |
| 本機長期 secret | `${file:~/.secrets/api_key.txt}` | 可透過檔案許可權管理 |
| 團隊共享配置 | 只保留變數名 | 每個人用自己的 secret 注入 |
| CI 或遠端環境 | 短期 token / OAuth | 更容易撤權和審計 |

> [!WARNING]
> **不要把 `<YOUR_PERSONAL_ACCESS_TOKEN>` 替換成真實 token 後提交**。教程、儲存庫、截圖和終端日誌都不應該包含真實認證值。

## 5. 企業 registry 與 whitelist

Teams 和 Enterprise 管理員可以開關 MCP access，也可以維護 whitelist。官方文件說明，企業團隊可以配置 custom MCP registries 替代預設 Windsurf MCP marketplace；registry 是管理 MCP access 的推薦方式，whitelist 也可用。

幾個關鍵規則：

- 配置多個 registry URL 時，Windsurf 會取 union，使用者看到所有 registry 合併後的 server。
- 一旦 whitelist 里加入任意 MCP server，非 whitelist server 會被團隊阻止。
- whitelist 的 Server ID 必須和使用者 `mcp_config.json` 裡的 key name 區分大小寫匹配。
- server matching 使用 regex full string matching，command、args、陣列長度都要匹配。

<details>
<summary>深讀：為什麼 registry 比複製配置更適合團隊</summary>

複製 `mcp_config.json` 的問題是來源不可控：有人從 Marketplace 裝，有人從 GitHub README 複製，有人改了 Docker image，有人硬編碼 token。最後團隊很難回答“這個 server 是否還被維護、是否擴大了許可權、誰負責升級”。

Registry 的價值是把允許使用的 server、版本來源、認證方式和維護責任集中管理。Whitelist 則是安全閘門：一旦開始使用 whitelist，非白名單 server 會被阻止，適合對生產資料和內部系統做最小授權。
</details>

上線前把每個 MCP server 記錄成一張准入卡：

| 欄位 | 需要寫清 |
| --- | --- |
| Server ID | 必須和配置 key 匹配，注意大小寫 |
| Transport | `stdio` / HTTP / SSE |
| Tools | 預設啟用哪些，哪些必須關閉 |
| Auth | env、file、OAuth 或企業憑據系統 |
| Data boundary | 會讀取哪些儲存庫、資料庫、檔案或 API |
| Write boundary | 是否能建立、更新、刪除、釋出或付款 |
| Owner | 誰負責升級、撤權、排障和審計 |

## 6. 商業專案接入順序

推薦按風險分三階段：

| 階段 | 接入物件 | 驗收標準 |
| --- | --- | --- |
| 第一階段 | issue、文件、只讀知識庫、只讀資料庫 schema、監控摘要 | 能減少複製上下文，不寫入生產系統 |
| 第二階段 | 帶寫入能力的內部工具 | 許可權拆細、人工確認、審計日誌可回放 |
| 第三階段 | 團隊 registry、whitelist、OAuth、撤權流程 | 成員離職、token 失效、server 超時都有處理路徑 |

MCP 接入完成的標誌不是“能呼叫成功”，而是失敗、越權、超時、撤權和敏感欄位返回時都有明確處理方式。

## 7. 排障先分類

| 現象 | 優先檢查 |
| --- | --- |
| server 不出現 | JSON 結構、key name、路徑、command、args |
| server 出現但呼叫失敗 | env/file 插值、token 作用域、過期時間、網路 |
| tools 太多或不相關 | MCP settings 的 tool toggles，是否超過 100 tools |
| whitelist 後被阻止 | Server ID 大小寫、regex full match、args 數量 |
| HTTP server 失敗 | `serverUrl` / `url`、HTTPS endpoint、headers、OAuth |

不要一上來刪除整個 Windsurf 配置目錄。保留失敗配置，複製一個最小 server 做對照，再逐項縮小問題範圍。

最小化排障順序：

1. 先停用其他 MCP，只保留一個 server。
2. 把寫入 tools 關掉，只測只讀 tool。
3. 確認 env/file 插值能在當前 shell 中讀到。
4. HTTP/SSE server 先用只讀 health endpoint 驗證網路和認證。
5. 再回到 Cascade 裡測試 tool 呼叫。

## 本章自檢

完成本章後，用這 4 個問題檢查：

1. 你接入的是隻讀 MCP，還是帶寫入能力的 MCP？
2. `mcp_config.json` 是否沒有硬編碼真實 token？
3. 是否只啟用了必要 tools，並知道 100 tools 總上限？
4. 團隊是否需要 registry、whitelist 和撤權流程？

透過標準：你能把 MCP 從“能裝上”推進到“許可權可控、認證可撤、失敗可排查”。

## 官方來源

- [Model Context Protocol (MCP)](https://docs.windsurf.com/windsurf/cascade/mcp) —— 官方 MCP 文件，覆蓋 Marketplace、deeplink、tools toggle、`mcp_config.json`、HTTP MCP、插值、admin controls、registry 和 whitelist。
- [MCP Specification](https://modelcontextprotocol.io) —— 官方 MCP 協議入口，用於核對 transports、registry schema 和 server 規範。

## 接下來去哪

<Cards>
  <Card title="Skills 與 Workflows" description="繼續判斷什麼時候寫能力包，什麼時候寫手動流程，什麼時候只寫規則。" href="/zh-Hant/docs/windsurf/official/05-skills-workflows" />
  <Card title="模型、用量與額度" description="繼續核對模型選擇、用量、quota 和 pricing 這類高波動事實。" href="/zh-Hant/docs/windsurf/official/06-models-usage" />
</Cards>
