oc/skills/opencode-config/references/03-mcp-servers.md

03 — MCP Servers (Model Context Protocol)

源: https://opencode.ai/docs/zh-cn/mcp-servers/ 适用: 在 opencode.json 的 mcp 段加本地/远程 MCP server,加 OAuth 配置,按代理管控

顶层结构

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "<server-name>": {
      "type": "local" | "remote",
      "enabled": true,
      // local 还需 command + 可选 environment
      // remote 还需 url + 可选 headers/oauth
      "timeout": 5000
    }
  }
}

enabled: false 临时禁用 (配置保留)。彻底删 → 从 mcp 段移除。

上下文成本警告: MCP 工具进 LLM 上下文,大量启用易爆上下文。Sentry / GitHub MCP 特别吃 token。

本地 (type: "local")

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true,
      "environment": { "BROWSER": "chromium" }
    }
  }
}

字段	必填	说明
type	✅	必须 "local"
command	✅	字符串数组,不是单个字符串
environment	❌	object, 启动时设置环境变量
enabled	❌	启动时启用/禁用
timeout	❌	ms, 默认 5000

远程 (type: "remote")

{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": { "Authorization": "Bearer MY_API_KEY" }
    }
  }
}

字段	必填	说明
type	✅	必须 "remote"
url	✅	远程 MCP server 地址
enabled	❌	—
headers	❌	object, 随请求发
oauth	❌	object | false
timeout	❌	ms, 默认 5000

OAuth

自动: 远程 server 触发 401 → opencode 自动走 OAuth 流程 (支持 RFC 7591 动态注册)。Token 存 ~/.local/share/opencode/mcp-auth.json。

预注册 (已有 client 凭据):

{
  "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 (用 API key 替代):

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

手动命令:

opencode mcp auth <server>          # 触发 OAuth (开浏览器)
opencode mcp auth list              # 列出所有支持 OAuth 的状态
opencode mcp list                   # 列出所有 MCP server + 状态
opencode mcp logout <server>        # 删凭据
opencode mcp debug <server>         # 调试: 状态/HTTP/OAuth 发现

按代理管控 (MCP 工具)

MCP 工具注册时带 server 前缀 (<server>_<tool>)。要用 tools.<server>_* glob:

全局禁用,只在特定代理开:

{
  "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 规则: * 零或多字符,? 恰好一个字符,其它字面值。

覆盖组织远程默认

组织可在 .well-known/opencode 端点发默认 MCP server,可能默认禁用。启用方法: 在本地配置加同名字段 + enabled: true。

官方示例 (照搬)

Sentry:

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

→ opencode mcp auth sentry → 浏览器 OAuth。

Context7 (查文档):

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

带 API key 提高速率:

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

提示: use context7 让代理用。也可在 AGENTS.md 写:

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

Grep by Vercel (搜 GitHub 代码):

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

→ 提示: use the gh_grep tool。

验证清单

1. type: local|remote 必填,command 是数组。
2. 远程 URL 正确,headers/oauth 字段拼写。
3. 退出重启 opencode。
4. opencode mcp list 看 server 状态。
5. 在 prompt 里 use <server> 试调,或用 mcp debug <server> 诊断。
6. 上下文吃紧 → 全局 tools.<server>*: false,按代理开。