MCP 伺服器

學習目標

• 理解 MCP 協定的核心概念
• 設定本地 MCP 伺服器（type: local）
• 設定遠端 MCP 伺服器（type: remote）
• 掌握 OAuth 認證流程
• 管理 MCP 工具權限
• 認識實用 MCP 伺服器範例

MCP 協定概述

Model Context Protocol（MCP）是一種開放標準，定義了 AI 代理如何與外部工具和資料來源互動。透過 MCP，你可以讓 opencode 代理存取資料庫、API、檔案系統等外部服務，大幅擴展代理的能力範圍。

啟用 MCP 伺服器

MCP 伺服器設定在 opencode.json 的 mcp 區塊中，每個伺服器需要一個唯一的名稱作為識別碼：

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "dist/index.js"]
    }
  }
}

MCP 伺服器有兩種主要類型：本地（local）和遠端（remote）。

本地 MCP 伺服器

本地 MCP 伺服器在你自己的機器上執行，透過標準 I/O（stdio）與 opencode 通訊。設定方式如下：

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "sentry": {
      "type": "local",
      "command": ["npx", "-y", "@opencode/sentry-mcp"]
    }
  }
}

command 是一個陣列，第一個元素是可執行檔路徑，其餘為傳遞給它的參數。opencode 會自動啟動並管理這個程序的生命週期。

command 陣列注意事項

command 必須是陣列形式（而非字串）。如果你習慣用字串寫指令，請務必自行拆分：

{
  // 正確：陣列形式
  "command": ["node", "server.js", "--port", "3000"]

  // 錯誤：字串形式（不支援）
  // "command": "node server.js --port 3000"
}

遠端 MCP 伺服器

遠端 MCP 伺服器透過 HTTP（Server-Sent Events）與 opencode 通訊，適合部署在雲端或遠端機器上：

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

遠端 MCP 參數說明

參數	說明	備註
type	伺服器類型	固定為 "remote"
url	MCP 伺服器的 SSE 端點	必須是有效的 HTTPS URL
headers	傳送給伺服器的 HTTP 標頭	用於 API 金鑰等認證資訊

OAuth 認證

遠端 MCP 伺服器支援 OAuth 2.0 認證流程。opencode 提供三種模式來處理 OAuth：

自動認證流程

當伺服器支援 OAuth 且 headers 中未提供認證資訊時，opencode 會自動啟動瀏覽器進行授權。流程如下：

1. opencode 打開瀏覽器前往伺服器的授權頁面
2. 你在瀏覽器中登入並授權
3. 授權完成後，瀏覽器顯示成功訊息，你可關閉該分頁
4. opencode 自動取得 token 並用於後續請求

預先註冊的 OAuth

你也可以在設定中預先註冊 OAuth 應用程式的用戶端資訊，適用於自建或私有 MCP 伺服器：

{
  "mcp": {
    "private-server": {
      "type": "remote",
      "url": "https://private.example.com/mcp",
      "oauth": {
        "client_id": "opencode-app",
        "authorization_url": "https://private.example.com/oauth/authorize",
        "token_url": "https://private.example.com/oauth/token"
      }
    }
  }
}

手動 Token 管理

如果你已有有效的 access token，可以直接在 headers 中指定，跳過 OAuth 流程：

{
  "mcp": {
    "api-server": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

MCP 工具管理

MCP 伺服器曝露的工具可以像內建工具一樣設定權限，甚至可以在全域層級停用、在特定代理中啟用：

{
  "permissions": {
    "mcp": {
      "filesystem": {
        "allow": ["read_file", "list_directory"],
        "ask": ["write_file", "create_directory"]
      },
      "sentry": "deny"
    }
  }
}

MCP 工具的名稱格式為 mcp/<server-name>/<tool-name>。你也可以使用簡潔語法，直接以伺服器名稱作為鍵：

{
  "permissions": {
    "mcp": {
      // 停用整個 filesystem 伺服器的所有工具
      "filesystem": "deny",
      // 只允許 sentry 伺服器的特定工具
      "sentry": {
        "allow": ["search_issues", "get_event"]
      }
    }
  }
}

在代理層級，你可以為特定代理啟用或停用 MCP 工具：

{
  "agents": {
    "debug-agent": {
      "permissions": {
        "mcp": {
          "sentry": "allow",
          "filesystem": "deny"
        }
      }
    }
  }
}

實際應用範例

Sentry MCP 伺服器

讓 opencode 直接查詢 Sentry 上的錯誤事件與效能資料：

{
  "mcp": {
    "sentry": {
      "type": "local",
      "command": ["npx", "-y", "@opencode/sentry-mcp"]
    }
  }
}

啟用後，你可以問代理：「幫我查一下昨天 production 環境最常發生的三個錯誤」，代理就會透過 Sentry MCP 工具自動查詢。

Context7 MCP 伺服器

Context7 提供技術文件檢索能力，讓代理在回答問題時能參考最新的套件文件：

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@context7/mcp-server"]
    }
  }
}

Grep by Vercel

在大型程式碼庫中快速搜尋特定模式：

{
  "mcp": {
    "grep": {
      "type": "local",
      "command": ["npx", "-y", "@opencode/grep-mcp"]
    }
  }
}

LSP 伺服器補充

除了 MCP，opencode 也支援 LSP（Language Server Protocol）伺服器，為編輯器提供程式碼補全、診斷、重構等功能。LSP 伺服器設定在專案目錄中安裝對應的 language server 即可，opencode 會自動偵測並啟用常見的 LSP（如 TypeScript、Rust Analyzer、Pyright 等）。

若要手動指定 LSP 伺服器，可以在 opencode.json 中設定：

{
  "lsp": {
    "enabled": true,
    "servers": {
      "typescript": {
        "command": ["node", "./node_modules/typescript-language-server/lib/cli.mjs", "--stdio"]
      }
    }
  }
}

實戰練習