为 opencode 接入 MCP server

opencode 可以通过 Model Context Protocol(MCP)接入外部工具,本地(子进程)和远程(HTTP)server 都支持,配置后 MCP 工具与内置工具并列可用。注意文档的提醒:每个 server 都会把工具定义塞进 context——文档点名 GitHub 的 server 容易吃满上下文。只开需要的。

`mcp` 配置项

在 opencode.json / opencode.jsonc 的 mcp 下定义 server,每个用唯一名字命名。prompt 里可以按名字引导模型使用(如「use context7」);enabled: false 则保留配置但暂时停用:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-server": { "enabled": true }
  }
}

组织可以通过 .well-known/opencode 下发 MCP 默认配置;本地 mcp 条目会覆盖它——比如对组织默认关闭的 server 设 enabled: true 来开启。配置合并规则见配置指南。

本地 server

本地 server 是一条由 opencode 负责拉起的命令:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "environment": { "LOG_LEVEL": "info" }
    }
  }
}

选项	必填	说明
`type`	是	必须为 `"local"`
`command`	是	可执行文件加参数,数组形式
`cwd`	否	工作目录;相对路径基于 workspace 解析
`environment`	否	传给 server 进程的环境变量
`timeout`	否	拉取工具的超时时间(ms),默认 5000

远程 server

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

{env:NAME} 是环境变量插值——凭证一律这样写,不要把密钥提交进配置文件。远程选项:url(必填)、headers、oauth、enabled、timeout(同样默认 5000 ms)。

OAuth

远程 OAuth 是全自动的:opencode 检测到 401 后走浏览器授权流程(支持时使用 RFC 7591 动态客户端注册),token 存放在 ~/.local/share/opencode/mcp-auth.json。如果你有预注册的 client 凭证,可以显式配置:

"oauth": {
  "clientId": "{env:MCP_CLIENT_ID}",
  "clientSecret": "{env:MCP_CLIENT_SECRET}",
  "scope": "tools:read tools:execute"
}

纯 API key 的 server 设 "oauth": false,完全跳过 OAuth。server 和凭证都走 CLI 管理:

opencode mcp add               # 交互式添加本地或远程 server
opencode mcp list              # server 列表及连接状态(简写 ls)
opencode mcp auth my-server    # 浏览器授权流程
opencode mcp auth list         # 列出支持 OAuth 的 server 及状态
opencode mcp logout my-server  # 删除已存凭证
opencode mcp debug my-server   # 连通性 + OAuth discovery 排查

控制 MCP 工具

MCP 工具以 server 名作为前缀注册,所以 tools 键支持 glob(* 匹配零个或多个字符,? 匹配一个)——先全局禁用,再给需要的 agent 单独放行。(tools 自 v1.1.1 起废弃——等价的 permission 规则用同样的 glob 写法,如 "my-server_*": "deny",见权限指南。)

{
  "$schema": "https://opencode.ai/config.json",
  "tools": { "my-server_*": false },
  "agent": {
    "reviewer": { "tools": { "my-server_*": true } }
  }
}

v2 差异

v2 重构了这块:server 挪到 mcp.servers 之下,disabled 取代 enabled,OAuth 字段改成 snake_case(client_id),mcp add 变成参数式(--url、--env、--header、--global),应用内用 /mcps 管理。本篇对应 v1 的配置。

mcp 配置项