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（以 Sentry 为例）的完整闭环。

第一步，确认连上。 配好 opencode.json 后跑：

opencode mcp list

输出里每个 MCP 会有一个认证状态。显示 configured / ready 才算通，error 要先 opencode mcp debug <名字> 排查（多半是 URL、密钥或 OAuth 没走完）。

第二步，进对话显式调用。 新挂的 MCP 有时候不会被模型自动选中（下一个坑会讲），所以第一次最好显式点名：

use sentry

帮我看一下 qunqin-blog 这个项目最近 24 小时有没有新报错，按频率排个序。

正常情况下模型会回一段工具调用的过程，类似：

→ mcp__sentry__list_issues(project="qunqin-blog", statsPeriod="24h")
← [{ id: "...", count: 3, title: "TypeError: ..." }, ...]

能看见这一行 → 调用和 ← 返回，说明整条链路通了——配置、鉴权、工具注册都没问题。

第三步，确认密钥没漏。 这个常被忽略：opencode.json 如果不小心提交进 Git，里面用 {env:...} 占位的部分是安全的，但 OAuth token 落在 ~/.local/share/opencode/mcp-auth.json——确认它在 .gitignore 覆盖范围内，或者干脆不放进仓库目录。

走完这三步，一个 MCP 才算真正「能用」，而不是「配上了」。

两个小坑

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

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