OpenCode 里配置 MCP

OpenCode 支持通过 MCP（Model Context Protocol）接入外部服务——本地跑的命令或远端 URL 都行。配置写在 JSON 里，跑起来以后模型就多了一批可调用的工具。

配置文件放哪

• 全局用：~/.config/opencode/opencode.json
• 只给当前仓库：项目根目录的 opencode.json，可以提交 Git

多处都有配置时，同名键后面覆盖前面，不冲突的键合并保留。文件头带上 Schema 方便编辑器补全：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

本地 MCP

type: "local"，command 是启动命令的数组：

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "environment": {
        "SOME_VAR": "value"
      }
    }
  }
}

environment 注入子进程的环境变量，适合放路径之类的非密钥配置。密钥用 {env:变量名} 占位从宿主 shell 里取，不要硬写进文件。

第一次配可以先接 @modelcontextprotocol/server-everything 验证整条链路通不通：

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

对话里说 use everything，确认工具列表出来了再换真正要用的 MCP。

远端 MCP

type: "remote"，填 url，要鉴权就在 headers 里加 Bearer，密钥同样用 {env:...}：

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

走 OAuth 的服务（比如 Sentry）更简单，oauth: {} 触发自动流程，之后手动跑一次 opencode mcp auth sentry 过浏览器登录：

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

OAuth 令牌落在 ~/.local/share/opencode/mcp-auth.json，不要提交进公开仓库。

常用 CLI

opencode mcp list          # 看所有 MCP 和认证状态
opencode mcp auth <名字>   # 手动触发 OAuth 登录
opencode mcp logout <名字> # 清凭证重登
opencode mcp debug <名字>  # 排查 HTTP / OAuth 问题

两个小坑

挂的 MCP 多了以后，模型有时候会假装没看见工具。提示里显式写 use xxx（xxx 是配置里的键名）能改善这个问题。

每个 MCP 都消耗上下文。GitHub 类的返回量特别大，窗口容易塞满——能少挂就少挂，或者用 tools + glob 按 agent 粒度限制。