连接 MCP 服务器

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

使用时可以在提示词里点名：

Use context7 to check the latest React Router docs.

名字要短且明确。`context7` 比 `my-documentation-search-server` 更适合日常使用。

OAuth 和密钥

远程 MCP 可能需要认证。OpenCode 支持自动 OAuth；首次使用时会打开浏览器授权，也可以手动运行认证命令。

opencode mcp auth context7

如果 MCP 使用 API Key，不要把 Key 写进配置文件，使用环境变量：

{
  "headers": {
    "Authorization": "Bearer {env:MY_API_KEY}"
  }
}

密钥配置的原则很简单：仓库里只放引用，不放真实值。

控制上下文和权限

MCP 工具会进入模型的工具列表。接太多会带来两个问题：

上下文变重。
模型更容易选错工具。

新手建议：

默认只启用 1-3 个最常用 MCP。
暂时不用的服务器设置 enabled: false。
对高风险 MCP 使用权限控制，例如先设为 ask。
给特定 Agent 开特定 MCP，不要所有 Agent 都共享全部工具。

如果一个 MCP 叫 `sentry`，它暴露的工具通常会带 `sentry_` 前缀。你可以用类似 `sentry_*` 的模式控制一组工具。

怎么判断配置有效

配置后先做三步验证：

列出 MCP，确认服务器存在。
如果需要认证，完成 OAuth 或 API Key 配置。
用一个只读问题测试工具是否能返回结果。

常用命令：

opencode mcp list
opencode mcp auth context7

第一次不要用会修改外部系统的 MCP 动作。先验证查询，再考虑写入。

什么时候放全局

放项目级配置：

只服务当前项目。
依赖当前仓库路径、项目 API、项目数据库。
团队需要共享同一套工具。

放全局配置：

每个项目都会用。
不依赖某个仓库。
你愿意长期维护它的凭据和权限。

多数 MCP 应该先放项目级，跑稳后再考虑全局。

新手常见坑

一口气接十几个 MCP，模型开始乱选工具。
把 API Key 写进 opencode.json。
忽略 OAuth 状态，以为配置了 URL 就能调用。
没给 MCP 起清楚名字，导致提示词里难以指定。
对能写入外部系统的 MCP 没有设置审批。

最近更新： 2026年5月1日

On this page