MCP Servers - MCP 服务器

你可以通过 Model Context Protocol（MCP） 向 OpenCode 添加外部工具。OpenCode 同时支持本地（local）和远程（remote）server。

一旦添加完成，MCP 工具会与内置工具一起，自动提供给 LLM 使用。

注意事项（Caveats）

当你使用 MCP server 时，它会占用 context（上下文）。如果你启用了很多工具，context 会很快被占满。因此，我们建议谨慎选择要使用的 MCP server。

某些 MCP server（例如 GitHub MCP server）通常会增加大量 token，很容易超过 context limit（上下文长度限制）。

启用（Enable）

你可以在 OpenCode Config 中的 mcp 节点下定义 MCP server。每一个 MCP 都需要一个唯一名称。你可以在 prompt（提示词）中通过名称引用该 MCP。

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

你也可以通过将 enabled 设置为 false 来禁用某个 server。这在你希望临时关闭某个 server，但又不想从配置中删除它时非常有用。

覆盖远程默认配置（Overriding remote defaults）

组织可以通过其 .well-known/opencode endpoint 提供默认的 MCP server。这些 server 可能默认是禁用的，允许用户按需选择启用。

如果你想启用组织远程配置中的某个 server，可以在本地配置中添加该 server，并设置 enabled: true：

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

你的本地配置会覆盖远程默认配置。更多细节请参考 config precedence。

本地 MCP（Local）

在 MCP 对象中，将 type 设置为 "local"，即可添加本地 MCP server。

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

command 用于指定如何启动本地 MCP server。你也可以通过 environment 传入一组环境变量。

例如，下面演示了如何添加测试用的 @modelcontextprotocol/server-everything MCP server：

```jsonc title=”opencode.jsonc” { “$schema”: “https://opencode.ai/config.json“, “mcp”: { “mcp_everything”: { “type”: “local”, “command”: [“npx”, “-y”, “@modelcontextprotocol/server-everything”], }, }, }

使用时，可以在 prompt 中添加 `use the mcp_everything tool`：
```txt "mcp_everything"
use the mcp_everything tool to add the number 3 and 4
使用 mcp_everything tool 计算 3 和 4 的和

配置项（Options）

下面是配置本地 MCP server 的所有可选项：

远程 MCP（Remote）

将 type 设置为 "remote"，即可添加远程 MCP server。

{
  "$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"
      }
    }
  }
}

url 表示远程 MCP server 的地址，通过 headers 可以传入自定义 HTTP header。

配置项（Options）

OAuth

OpenCode 会自动处理远程 MCP server 的 OAuth 认证流程。当 server 需要认证时，OpenCode 会：

1. 检测到 401 响应并自动启动 OAuth 流程
2. 如果 server 支持，则使用 Dynamic Client Registration（RFC 7591）
3. 安全地存储 token，供后续请求使用

自动模式（Automatic）

对于大多数支持 OAuth 的 MCP server，不需要额外配置，只需配置远程 server 即可：

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

如果 server 需要认证，当你第一次使用时，OpenCode 会提示你完成认证。如果没有自动触发，也可以通过 opencode mcp auth <server-name> 手动触发认证流程。

预注册模式（Pre-registered）

如果你已经从 MCP server 提供方获取了 client credentials，可以手动配置：

{
    "$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"
    }
}
}
}

认证操作（Authenticating）

你可以手动触发认证或管理凭证。

对指定 MCP server 进行认证：

opencode mcp auth my-oauth-server

列出所有 MCP server 及其认证状态：

opencode mcp list

删除已保存的认证信息：

opencode mcp logout my-oauth-server

mcp auth 命令会打开浏览器完成授权流程。授权完成后，OpenCode 会将 token 安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

禁用 OAuth（Disabling OAuth）

如果你希望对某个 server 禁用自动 OAuth（例如使用 API Key 的 server），可以将 oauth 设置为 false：

{
"$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 配置项（OAuth Options）

调试（Debugging）

如果远程 MCP server 认证失败，可以使用以下命令进行排查：

# 查看所有支持 OAuth 的 server 的认证状态
opencode mcp auth list
# 调试指定 server 的连接和 OAuth 流程
opencode mcp debug my-oauth-server

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

管理（Manage）

你的 MCP 会作为 tools 出现在 OpenCode 中，与内置工具一起使用。因此你可以像管理普通工具一样，通过 OpenCode config 来管理它们。

全局管理（Global）

你可以在全局范围内启用或禁用 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 pattern（通配模式）来批量禁用 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
    }
}

这里使用了 glob pattern my-mcp* 来禁用所有匹配的 MCP。

按 Agent 管理（Per agent）

如果你有大量 MCP server，可能希望只在某些 agent 中启用，而在全局禁用。可以按以下步骤操作：

1. 在全局 tools 中禁用它。
2. 在 agent config 中为指定 agent 启用该 MCP tool。

{
"$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 patterns）

glob pattern 使用简单的正则通配规则：

• *：匹配零个或多个任意字符（例如 "my-mcp*" 可匹配 my-mcp_search、my-mcp_list 等）
• ?：匹配任意单个字符
• 其他字符按字面值精确匹配

示例（Examples）

下面列出了一些常见 MCP server 的示例。如果你想补充其他 server，可以提交 PR。

Sentry

添加 Sentry MCP server，用于与你的 Sentry 项目和 issue 进行交互。

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

配置完成后，执行认证：

opencode mcp auth sentry

该命令会打开浏览器完成 OAuth 授权，并将 OpenCode 连接到你的 Sentry 账号。

认证完成后，你就可以在 prompt 中使用 Sentry tools 查询 issue、project 和 error 数据。

Show me the latest unresolved issues in my project. use sentry
显示我项目中最新的未解决 issue。use sentry

Context7

添加 Context7 MCP server，用于搜索文档。

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "context7": {
            "type": "remote",
            "url": "https://mcp.context7.com/mcp"
        }
    }
}
如果你注册了免费账号，可以使用 API Key 来获得更高的 rate-limit。
```json
{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "headers": {
            "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
            }
        }
    }
}

这里假设你已经设置了环境变量 CONTEXT7_API_KEY。

在 prompt 中添加 use context7 即可使用 Context7 MCP server。

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
使用 context7 配置一个 Cloudflare Worker 脚本，将 JSON API 响应缓存 5 分钟。

你也可以在 AGENTS.md 中加入类似规则：

当需要搜索文档时，使用 `context7` tools。

Grep by Vercel

添加 Grep by Vercel MCP server，用于搜索 GitHub 上的代码片段。

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

由于我们将 MCP server 命名为 gh_grep，因此在 prompt 中可以添加 use the gh_grep tool 来让 agent 使用它。

```txt “use the gh_grep tool” What’s the right way to set a custom domain in an SST Astro component? use the gh_grep tool 在 SST Astro component 中设置自定义域名的正确方式是什么？use the gh_grep tool

你也可以在 [AGENTS.md](/docs/rules/) 中添加类似说明：
```md title="AGENTS.md"
如果不确定如何实现某个功能，请使用 `gh_grep` 在 GitHub 中搜索代码示例。