跳轉到主要內容
文件擴充生態MCP 整合

MCP 整合

給 workflow 裡的 Agent 掛載任意 MCP Server 作為工具，擴充它能做的事。

MCP（Model Context Protocol）是一個開放協議，用統一的方式把外部工具提供給 LLM。在 Braidrun 裡，MCP 掛在 Agent 上：給某個 Agent 設定一個或多個 MCP server，這些 server 暴露的工具就和內建工具一樣，出現在該 Agent 可呼叫的工具列表裡。

運作原理

MCP 設定是 Agent 級的：在工作流 YAML 裡，每個 Agent 的 mcp_servers 是一個「名字 → 設定」的對應，可以同時掛多個 server。步驟執行前，執行時逐個連接這些 server，把它們的工具併入該 Agent 的工具註冊表。

某個 MCP server 連接失敗時，執行時記一條警告並跳過它的工具，不會中斷整條工作流 —— 其餘 server 與內建工具照常可用。如果某個步驟相依的工具來自沒連上的 server，失敗會體現在那個步驟的執行日誌裡。

掛一個本地 stdio server

最常見的形式：MCP server 是一個本地行程，執行時用 command + args 把它啟動起來，透過標準輸入輸出通訊。用 preset 宣告 Agent 時，mcp_servers 寫在 overrides 裡：

yaml
agents:
  researcher:
    preset: universal
    overrides:
      mcp_servers:
        github:
          command: npx
          args: ["-y", "@modelcontextprotocol/server-github"]
          env:
            GITHUB_PERSONAL_ACCESS_TOKEN: "<your-token>"
          description: "读写 GitHub 仓库与 issue"
preset 模式下必須放 overrides

Agent 宣告了 preset 時，執行時只合併 preset 預設值與 overrides 裡的欄位；寫在 Agent 頂層的 mcp_servers 會被忽略。

連接遠端 server

MCP server 也可以是一個網路服務：填 url 就不再走 stdio，type 決定傳輸方式（sse、websocket、http），不填 type 按 sse 處理。

yaml
agents:
  analyst:
    preset: universal
    overrides:
      mcp_servers:
        crm:
          url: "https://mcp.example.com/sse"
          type: sse
          timeout: 60000
        docs-search:
          url: "https://mcp.example.com/mcp"
          type: http
          enabled: true

url 指向的服務必須能從工作流的執行環境存取到 —— 寫公網可達的位址，不要寫只在你本機可存取的位址。

欄位參考

字段說明
commandstdio 模式的啟動命令（可執行檔名或路徑）；stdio 模式下必填
args命令列參數列表
env傳給 stdio 子行程的環境變數；憑證從這裡傳
cwdstdio 子行程的工作目錄，不填用執行時預設
url遠端 server 位址；填了 url 就不再走 stdio
type傳輸類型：stdio（預設）、sse、websocket、http；只在填了 url 時生效，不填按 sse 處理
timeout逾時，單位毫秒，預設 30000
enabled預設 true；設為 false 可以暫時停用一個 server 而不刪設定
description備註，幫助協作者理解這個 server 是做什麼的

憑證與網路注意事項

  • stdio 子行程不會繼承執行環境的全部變數：只有 PATH、HOME、LANG 等少量基礎變數，加上你在 env 裡顯式寫的內容會傳進去。MCP server 需要的 API Key 必須顯式寫在 env 裡。
  • env 的值以明文儲存在工作流 YAML 裡。分享工作流或發布範本之前，把真實密鑰換成佔位符，讓使用者填自己的。
  • 遠端 server 建議用 HTTPS 位址；連接失敗按上面說的跳過處理，可以先在執行日誌裡確認工具是否註冊成功。
  • 工具越多，Agent 的決策空間越大。只掛這個 Agent 真正會用到的 server，成功率與速度都會更好。

Braidrun 工具的 MCP 暴露

這條路也是雙向的：Braidrun 自身的內建工具打包成了一個 stdio MCP server（名為 braidrun-workflow），同一套工具可以經 MCP 協議提供給其他 MCP 用戶端重複使用。

與 Claude Code / Codex 的關係

在產品內，AI 助理可以選用 Koog、Claude Code 或 Codex 作為執行時，支援訂閱登入代替 API Key。執行時切換見 AI 助理文件。

相關頁面