第 11 章：MCP 伺服器與 ACP 擴展

11.1 什麼是 MCP？

MCP（Model Context Protocol）是一種開放式通訊協定，允許 OpenCode 與外部工具服務進行標準化互動。你可以將 MCP 想像成 AI 代理的「USB 埠」——它定義了一套統一的介面，讓任何符合規範的工具都能即插即用。

當代理需要執行超出其內建能力的任務時（如查詢資料庫、建立 GitHub Issue、傳送 Slack 訊息），MCP 伺服器就扮演了橋樑角色。代理透過 MCP 協定發送請求，伺服器執行對應操作並回傳結果。

11.2 本地 MCP 伺服器

本地 MCP 伺服器與 OpenCode 執行在同一台機器上，透過標準輸入輸出（stdio）或本機 TCP 連接進行通訊。這是最常見的 MCP 部署方式，適合整合本地資料庫、檔案系統工具或內部腳本。

設定本地 MCP

MCP 伺服器設定在 opencode.json 的 mcp 欄位中：

{
  "mcp": {
    "servers": {
      "sqlite-explorer": {
        "command": "node",
        "args": ["mcp-servers/sqlite-server.js"],
        "env": {
          "DB_PATH": "./data/app.db"
        }
      },
      "file-manager": {
        "command": "python",
        "args": ["mcp-servers/file-manager.py"],
        "transport": "stdio"
      },
      "local-llm": {
        "command": "ollama",
        "args": ["run", "llama3"],
        "transport": "stdio"
      }
    }
  }
}

11.3 遠端 MCP 伺服器

遠端 MCP 伺服器透過 HTTPS 或 WebSocket 連接，讓 OpenCode 能夠與雲端服務互動。這對於整合第三方 API（如 GitHub、Slack、Jira）特別有用。

{
  "mcp": {
    "servers": {
      "github-mcp": {
        "url": "https://mcp.example.com/github",
        "transport": "sse",
        "headers": {
          "Authorization": "Bearer ${GITHUB_TOKEN}"
        }
      },
      "sentry-mcp": {
        "url": "https://mcp.sentry.io/v1",
        "transport": "https"
      }
    }
  }
}

11.4 OAuth 認證支援

對於需要使用者授權的遠端 MCP 伺服器，OpenCode 提供了完整的 OAuth 2.0 支援：

自動認證流程

當代理首次嘗試使用需要 OAuth 的 MCP 伺服器時，OpenCode 會自動啟動 OAuth 授權流程：

1. 代理嘗試呼叫 MCP 工具
2. 系統偵測到需要 OAuth 授權
3. 自動打開瀏覽器引導使用者完成授權
4. 取得 access token 並安全儲存
5. 後續呼叫自動帶入 token

預先註冊

開發者也可以預先在設定檔中註冊 OAuth 憑證：

{
  "mcp": {
    "oauth": {
      "github-mcp": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "scopes": ["repo", "issues"],
        "redirect_uri": "http://localhost:3456/callback"
      }
    },
    "servers": {
      "github-mcp": {
        "url": "https://mcp.github.com/v1",
        "auth": "oauth"
      }
    }
  }
}

11.5 常用 MCP 伺服器範例

以下是一些經過驗證的熱門 MCP 伺服器設定，可以直接複製使用：

{
  "mcp": {
    "servers": {
      "sentry": {
        "description": "查詢 Sentry 錯誤與效能資料",
        "url": "https://mcp.sentry.io/v1",
        "transport": "https",
        "headers": {
          "Authorization": "Bearer ${SENTRY_API_KEY}"
        }
      },
      "context7": {
        "description": "500+ 框架的官方文件檢索",
        "url": "https://mcp.context7.com/v1",
        "transport": "https",
        "headers": {
          "X-API-Key": "${CONTEXT7_API_KEY}"
        }
      },
      "grep-app": {
        "description": "GitHub 開源程式碼搜尋",
        "url": "https://mcp.grep.app/v1",
        "transport": "https",
        "auth": "oauth"
      }
    }
  }
}

11.6 MCP 管理與安全

OpenCode 允許針對不同代理設定不同的 MCP 伺服器。這在多代理協作場景中非常重要——每個代理只需要載入與其任務相關的 MCP：

{
  "agents": {
    "Sisyphus": {
      "mcps": ["context7", "grep-app"]
    },
    "dev-agent": {
      "mcps": ["sentry", "github-mcp"]
    },
    "explore": {
      "mcps": ["context7"]
    }
  }
}

11.7 ACP：代理通訊協定

ACP（Agent Communication Protocol）是 OpenCode 特有的通訊協定，專門用於代理之間的直接溝通。與 MCP（工具與代理之間的通訊）不同，ACP 讓代理可以相互交換訊息、共享上下文、協調任務。

ACP 的核心功能

ACP vs MCP

📝 本章測驗

❓ 常見問題