MCP 整合

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

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

1. 新增 MCP 的三條路徑

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

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

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

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 基礎結構

手動配置檔案在：

~/.codeium/windsurf/mcp_config.json

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

{
  "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。

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

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

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

4. 不要把金鑰寫死

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

支援兩種模式：

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

使用建議：

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、陣列長度都要匹配。

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

6. 商業專案接入順序

推薦按風險分三階段：

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

7. 排障先分類

不要一上來刪除整個 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) —— 官方 MCP 文件，覆蓋 Marketplace、deeplink、tools toggle、mcp_config.json、HTTP MCP、插值、admin controls、registry 和 whitelist。
• MCP Specification —— 官方 MCP 協議入口，用於核對 transports、registry schema 和 server 規範。

接下來去哪