OpenCode 通过 MCP（Model Context Protocol）扩展 AI 可用的工具集，支持本地（subprocess）和远程（HTTP）两种类型。在 opencode.json 的 mcp 字段中配置，每个 MCP 服务器有唯一名称，AI 可在 prompt 中通过名称引用它。MCP 工具会占用 context，工具较多时注意选择性启用，可全局禁用再按 agent 开启。

OpenCode MCP 扩展工具

OpenCode 通过 Model Context Protocol（MCP）支持接入外部工具。MCP 工具添加后，AI 可以像使用内置工具一样使用它们。

注意：每个 MCP 服务器都会占用 context 窗口。工具越多，消耗越大，GitHub MCP 等工具尤其会消耗大量 token。建议按需启用。

---

基本配置

在 opencode.json 的 mcp 字段下配置，每个服务器使用唯一名称：

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

设 enabled: false 可临时禁用某个服务器，而不需要删除配置。

---

本地 MCP（type: local）

本地 MCP 通过启动子进程运行：

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

command 数组的第一个元素是可执行文件，后面是参数。也可以用 bun x：

"command": ["bun", "x", "my-mcp-command"]

本地 MCP 配置项

选项	类型	必填	说明
type	String	是	固定为 "local"
command	Array	是	启动命令及参数
environment	Object	—	传给子进程的环境变量
enabled	Boolean	—	是否在启动时加载
timeout	Number	—	获取工具列表的超时（ms），默认 5000

示例：server-everything 测试服务器

{
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

在 prompt 中使用：

use the mcp_everything tool to add the number 3 and 4

---

远程 MCP（type: remote）

远程 MCP 通过 HTTP 连接到外部服务器：

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

远程 MCP 配置项

选项	类型	必填	说明
type	String	是	固定为 "remote"
url	String	是	MCP 服务器 URL
enabled	Boolean	—	是否在启动时加载
headers	Object	—	随请求发送的 HTTP 头
oauth	Object | false	—	OAuth 认证配置
timeout	Number	—	获取工具列表的超时（ms），默认 5000

---

OAuth 认证

OpenCode 自动处理 OAuth 认证流程。服务器返回 401 时，OpenCode 会：

1. 检测到需要认证
2. 尝试使用动态客户端注册（RFC 7591）
3. 安全存储 token 供后续使用

自动 OAuth（无需额外配置）

大多数支持 OAuth 的 MCP 服务器只需配置 URL：

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

首次使用时 OpenCode 会引导你完成认证。也可以手动触发：

opencode mcp auth <server-name>

预注册凭证

如果 MCP provider 已提供了客户端凭证：

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

OAuth 管理命令

opencode mcp auth my-server       # 认证（打开浏览器）
opencode mcp list                  # 列出所有 MCP 及认证状态
opencode mcp logout my-server      # 清除存储的凭证
opencode mcp auth list             # 查看所有 OAuth 服务器状态
opencode mcp debug my-server       # 调试连接和 OAuth 流程

Token 存储在 ~/.local/share/opencode/mcp-auth.json。

禁用 OAuth

对于使用 API Key 而非 OAuth 的服务器：

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

---

管理 MCP 工具

全局禁用

可以在 tools 字段中禁用特定 MCP：

{
  "mcp": {
    "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-foo"] },
    "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-bar"] }
  },
  "tools": {
    "my-mcp-foo": false
  }
}

Glob 模式

用 glob 一次禁用多个 MCP：

{
  "tools": {
    "my-mcp*": false
  }
}

Glob 规则：* 匹配任意字符，? 匹配单个字符。MCP 工具名格式为 {服务器名}_{工具名}，所以禁用某个服务器的所有工具用：

{ "mymcpservername_*": false }

按 Agent 启用

工具数量较多时，推荐全局禁用，只在需要的 agent 中启用：

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

---

实用 MCP 示例

Sentry

接入 Sentry，在 prompt 中查询项目 issues：

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

opencode mcp auth sentry   # 通过浏览器完成 OAuth

Show me the latest unresolved issues in my project. use sentry

Context7（文档查询）

查询各类库的最新文档：

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

在 AGENTS.md 中配置自动使用：

When you need to search docs, use `context7` tools.

Grep by Vercel（GitHub 代码搜索）

搜索 GitHub 上的代码示例：

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

What's the right way to set a custom domain in SST? use the gh_grep tool

---

常见问题

Q: 添加 MCP 后怎么知道 AI 能不能用到它？

A: 在 prompt 中明确说 use the {mcp-name} tool（如 use the gh_grep tool），或在 AGENTS.md 里配置默认行为。也可以用 opencode mcp list 确认服务器状态。

Q: 本地 MCP 服务器启动失败怎么排查？

A: 先在终端直接运行 command 数组里的命令（如 npx -y my-mcp-command），确认能正常启动。另外检查 timeout 是否够长（默认 5 秒，复杂的 MCP 可能需要更长时间初始化）。

Q: 能同时添加多少个 MCP 服务器？

A: 数量没有硬限制，但每个 MCP 的工具描述都会占用 context。建议按需启用，并使用按 agent 启用的方式控制不同场景下可用的工具集。