連線 MCP 伺服器

你是 OpenCode MCP 接入顧問。

【角色】
OpenCode MCP 接入顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 要接的 MCP server：___
- 本地還是遠端：___
- 需要的憑據：___
- 期望它做什麼：___
- 經驗水平：___

【工作流程】
1. 按本地 / 遠端定形態
2. 給設定和最小樣例
3. 說明憑據安全傳入
4. 限定許可權
5. 給接通驗證

【輸出規範】
▌一、形態判斷
▌二、設定 + 樣例
▌三、憑據安全
▌四、許可權 + 驗證

【硬約束】
- 憑據走安全儲存不進儲存庫
- 預設最小許可權
- 外部返回視為不可信
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

MCP 伺服器可以把外部系統接進 OpenCode，例如文件搜尋、GitHub、Sentry、資料庫、程式碼搜尋或內部服務。接入後，MCP 暴露的工具會和內建工具一起提供給模型使用。

先給結論：MCP 只接真正需要的外部上下文

每個 MCP 都會增加模型可見工具，也會增加上下文成本。工具越多，模型越慢、越容易選錯工具，也越容易觸碰不該碰的外部系統。

flowchart LR
    Need["需要外部上下文"] --> Builtin{"內建工具夠用?"}
    Builtin -->|夠| Stop["不接 MCP"]
    Builtin -->|不夠| OneTime{"只是一次性查資料?"}
    OneTime -->|是| Web["用 webfetch / search"]
    OneTime -->|否| MCP["設定 MCP"]
    MCP --> ReadOnly["先只讀驗證"]
    ReadOnly --> Scope["按許可權 / agent 收窄"]
    Scope --> Write["再考慮寫入型工具"]

    style Stop fill:#dcfce7,stroke:#22c55e
    style MCP fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Write fill:#fee2e2,stroke:#ef4444

1. 最小設定

MCP 配在 opencode.json / opencode.jsonc 的 mcp 欄位下。每個 server 要有唯一名字，prompt 裡也可以用這個名字指定工具。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

臨時不用時，不要刪除設定，直接關掉：

{
  "mcp": {
    "context7": {
      "enabled": false
    }
  }
}

名字要短而清楚。context7、sentry、gh_grep 比 my-documentation-search-server 更容易在 prompt 裡準確指定。

2. 本地和遠端怎麼選

本地 MCP 最少需要 type: "local" 和 command：

{
  "mcp": {
    "my-local": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

遠端 MCP 最少需要 type: "remote" 和 url，可以加 headers、oauth 和 timeout。

3. 遠端組織預設值

官方文件說明，組織可以透過 .well-known/opencode endpoint 提供預設 MCP server。這些 server 可能預設關閉，讓使用者按需啟用。

本地設定可以覆蓋遠端預設值。例如組織提供了 jira，你可以在本地啟用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

這類能力適合企業集中設定，但仍要遵守最小啟用原則。

4. OAuth 和認證

OAuth（Open Authorization，開放授權）是一套讓第三方應用安全訪問賬號資源的標準協議。你登入"用 GitHub 賬號登入其他網站"看到的跳轉流程就是它。OpenCode 用 OAuth 是為了不讓你把 password / API key 寫進設定——瀏覽器跳一下、授權一次，token 自動存到本機。

遠端 MCP 可能需要認證。OpenCode 會在收到 401 時啟動 OAuth flow（讓瀏覽器開啟授權頁，使用者登入後回跳併發回 token），並在 server 支援它的情況下使用 Dynamic Client Registration（RFC 7591，讓 OpenCode 自己向 OAuth server 註冊 client，不用你提前去 server 後臺手動建 client_id）。認證 token 會存到：

~/.local/share/opencode/mcp-auth.json

常用命令：

opencode mcp list
opencode mcp auth <server-name>
opencode mcp logout <server-name>
opencode mcp auth list
opencode mcp debug <server-name>

mcp auth 會開啟瀏覽器授權；mcp debug 會檢查目前認證狀態、HTTP 連通性和 OAuth discovery flow。

如果 server 使用 API key，不走 OAuth，可以顯式關閉自動 OAuth：

{
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

如果 provider 給了預註冊 OAuth client，也可以設定 clientId、clientSecret 和 scope，同樣優先走環境變數。

5. 控制工具可見範圍

MCP 工具會進入 OpenCode 工具列表。官方文件裡可以用 tools 關閉某個 MCP 或一組 MCP 工具：

{
  "tools": {
    "my-mcp*": false
  }
}

MCP server tools 通常會以 server name 作為字首註冊。要關閉某個 server 的全部工具，可以使用類似：

{
  "tools": {
    "sentry_*": false
  }
}

tools 控制“工具是否可見”，permission 控制“可見工具被呼叫時 allow / ask / deny”。這兩個不是同一層。

6. 按 agent 開放 MCP

如果 MCP 很多，推薦全域關掉，再給特定 agent 開啟。思路是：

1. 在全域 tools 裡停用 MCP 工具。
2. 在特定 agent.tools 裡啟用需要的 MCP。

這比所有 agent 共享所有 MCP 更穩。比如 Sentry 工具只給排障 agent，文件搜尋只給研究 agent，資料庫只給只讀診斷 agent。

7. 常見 MCP 示例

示例的重點不是把所有 MCP 常駐開啟，而是先用一個只讀問題驗證認證、上下文和輸出質量。

8. 驗收清單

接入 MCP 後，至少檢查：

• 只啟用了真正高頻的 1-3 個 MCP。
• opencode mcp list 能看到 server 狀態。
• 需要 OAuth 的 server 已完成認證。
• API key 透過環境變數引用，不在設定檔裡明文出現。
• 寫入型外部工具預設 ask 或不可見。
• 大型 MCP 按 agent 開啟，不給所有 agent。
• 工具名短，prompt 裡容易指定。
• 出問題時能用 mcp debug 定位。

接下來去哪

官方資料

• OpenCode MCP servers：https://opencode.ai/docs/mcp-servers
• OpenCode Config：https://opencode.ai/docs/config
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Permissions：https://opencode.ai/docs/permissions