連線 MCP 伺服器

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