# 03 — MCP Servers (Model Context Protocol)

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

## 顶层结构

```json
{
  "$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"`)

```json
{
  "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"`)

```json
{
  "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 凭据):

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

**禁用自动 OAuth** (用 API key 替代):

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

**手动命令**:

```bash
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:

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

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

## 覆盖组织远程默认

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

## 官方示例 (照搬)

**Sentry**:

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

→ `opencode mcp auth sentry` → 浏览器 OAuth。

**Context7** (查文档):

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

带 API key 提高速率:

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

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

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

**Grep by Vercel** (搜 GitHub 代码):

```json
{ "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`,按代理开。