为 OpenCode 挂载外部能力：MCP 服务器完全指南

模型上下文协议（MCP）让 OpenCode 能够对接外部工具，无论是运行在本地的命令行程序，还是部署在远端的 HTTP 服务。一旦接入，这些 MCP 提供的工具就会和内置功能一样，自动出现在大语言模型的可用工具列表中，直接通过对话进行调用。

使用前的必要提醒

每个 MCP 服务器都会占用一部分上下文窗口。如果同时启用大量工具，很容易塞满 token 配额，尤其是一些返回数据量庞大的服务器。一个典型的例子是 GitHub MCP 服务器，它往往会拉入大量信息，稍不留神就可能超出上下文限制。因此，只开启真正需要的 MCP 服务器，是保持会话高效的关键原则。

启用 MCP 服务器

所有 MCP 服务器都在 opencode.json 配置文件的 mcp 字段下定义。每个服务器拥有一个独一无二的名字，后续在提示词中可以直接引用这个名字来调用工具。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"name-of-mcp-server": {
// …
"enabled": true
},
"name-of-other-mcp-server": {
// …
}
}
}

如果只是暂时不想使用某个服务器，可以将其 enabled 设为 false，这样无需从配置中删除即可关闭。

覆盖组织远程默认值

一些团队会通过 /.well-known/opencode 端点提供默认的 MCP 服务器列表。这些远程预设可能是默认禁用的，供成员按需启用。要想激活某个来自组织远程配置的服务器，只需在本地配置中声明同名条目，并将 enabled 设为 true。本地配置的优先级会覆盖远程默认设置。

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

添加本地 MCP 服务器

将 type 设为 "local" 即可定义本地服务器。command 字段负责指定启动该服务器的命令和参数，还可通过 environment 对象注入环境变量。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-local-mcp-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true,
"environment": {
"MY_ENV_VAR": "my_env_var_value"
}
}
}
}

一个实际例子是接入官方的测试服务器 @modelcontextprotocol/server-everything：

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

配置完成后，在提示词中写上“使用 mcp_everything 工具把 3 和 4 相加”，模型就会自动调用对应的运算工具。

本地 MCP 配置选项

添加远程 MCP 服务器

将 type 设为 "remote"，并指定 url 即可接入远程 HTTP MCP 服务。同时可以携带自定义请求头，比如用于 API 密钥鉴权的 Authorization 头。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com",
"enabled": true,
"headers": {
"Authorization": "Bearer MY_API_KEY"
}
}
}
}

远程 MCP 配置选项

OAuth 认证

远程 MCP 服务器如果需要授权，OpenCode 会自动处理 OAuth 流程。当服务端返回 401 状态码时，会触发以下动作：

• 尝试使用动态客户端注册（RFC 7591，若服务器支持）
• 安全存储令牌供后续请求使用

自动模式

绝大多数支持 OAuth 的 MCP 服务器无需额外配置，直接填写 URL 即可。若服务器要求授权，第一次尝试使用时会弹出认证提示；也可以手动执行 opencode mcp auth <服务器名> 来启动流程。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-oauth-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp"
}
}
}

预注册客户端凭证

如果已经从服务方拿到了客户端 ID 和密钥，可以直接写入配置：

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-oauth-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "{env:MY_MCP_CLIENT_ID}",
"clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
"scope": "tools:read tools:execute"
}
}
}
}

凭证管理命令

手动管理认证状态可以使用以下终端命令：

• 对指定服务器发起认证：opencode mcp auth my-oauth-server
• 列出所有 MCP 服务器及认证状态：opencode mcp list
• 移除已存储的凭证：opencode mcp logout my-oauth-server

执行 mcp auth 命令会打开系统浏览器进行授权，完成后令牌会安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

关闭自动 OAuth

对于使用 API 密钥而非 OAuth 的服务器，可将 oauth 设为 false 来禁用自动认证检测，同时仍可通过 headers 传递密钥：

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-api-key-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}"
}
}
}
}

OAuth 选项细节

调试连接问题

当远程 MCP 服务器认证失败时，可以使用调试命令定位问题：

# 查看所有具备 OAuth 能力的服务器认证状态
opencode mcp auth list

# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 命令会显示当前认证状态、测试 HTTP 连通性，并尝试执行 OAuth 发现流程。

精细控制 MCP 工具

接入的 MCP 服务器会以工具形式出现在 OpenCode 中，与内置工具并列。可以在 tools 字段中像控制其他工具一样管理它们。

全局启用/禁用

直接对 MCP 服务器名进行全局开关设定：

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp-foo": {
"type": "local",
"command": ["bun", "x", "my-mcp-command-foo"]
},
"my-mcp-bar": {
"type": "local",
"command": ["bun", "x", "my-mcp-command-bar"]
}
},
"tools": {
"my-mcp-foo": false
}
}

也可以使用 glob 通配符批量禁用所有匹配的服务器工具。例如，下面这条配置禁用了所有以 my-mcp 开头的 MCP 服务器：

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp-foo": {
"type": "local",
"command": ["bun", "x", "my-mcp-command-foo"]
},
"my-mcp-bar": {
"type": "local",
"command": ["bun", "x", "my-mcp-command-bar"]
}
},
"tools": {
"my-mcp*": false
}
}

按代理（agent）启用

当 MCP 服务器数量较多时，更推荐的做法是全局禁用，只让特定的代理启用。首先在全局工具中将其关闭，然后在目标代理的配置里重新打开：

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp": {
"type": "local",
"command": ["bun", "x", "my-mcp-command"],
"enabled": true
}
},
"tools": {
"my-mcp*": false
},
"agent": {
"my-agent": {
"tools": {
"my-mcp*": true
}
}
}
}

关于 glob 模式

OpenCode 的 glob 支持简单规则：

• * 匹配零个或多个任意字符（如 my-mcp* 能匹配 my-mcp_search、my-mcp_list 等）
• ? 匹配恰好一个字符
• 其他字符原样匹配

有一点需要特别留意：MCP 服务器注册工具时，工具名会带上服务器名称作为前缀。所以，要禁用某个服务器的全部工具，只需使用 "服务器名_*": false 即可。

常见 MCP 服务器示例

以下是一些常用服务器的具体配置，开发者也可以向文档仓库提交 PR 来补充更多案例。

Sentry

接入 Sentry MCP 服务器后，可以直接在对话中查询项目和问题数据。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}

配置好之后，运行 opencode mcp auth sentry 完成浏览器中的 OAuth 授权。接下来就能在提示词里使用 use sentry 要求模型获取最新未解决的 issue 等信息。

Context7

Context7 提供文档搜索能力，适合在需要查阅最新技术资料时调用。

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

如果已经注册了 Context7 的免费账户，还可以提供 API 密钥来获得更高的速率限额。下面的写法假设环境变量 CONTEXT7_API_KEY 已经设置好：

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

使用时在提示词中加入 use context7 即可，也可以在 AGENTS.md 中写入类似指令，让模型自动在需要时搜索文档。

Vercel 的 Grep

Grep 工具能够搜索 GitHub 上的公开代码片段，适合查找实际用例。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
}
}
}

由于这里给它取名 gh_grep，提示词中可以使用 use the gh_grep tool 来让模型调用。类似的，也可以在 AGENTS.md 里指示模型在不熟悉某个用法时主动使用 gh_grep 搜索 GitHub 代码示例。

通过 MCP 机制，OpenCode 将外部工具与语言模型的交互变得极其顺畅。从本地脚本到需要 OAuth 授权的远程服务，只需一份简洁的 JSON 配置，所有工具就能像内置功能一样被大模型理解和调用。配合灵活的启用策略和 glob 控制，即使在多代理、多工具的复杂环境下，依然能够保持上下文的高效利用。