连接 MCP 服务器

MCP 服务器可以把外部系统接进 OpenCode，例如文档搜索、GitHub、Sentry、数据库、代码搜索或内部服务。接入后，MCP 暴露的工具会和内置工具一起提供给模型使用。

先给结论：MCP 只接真正需要的外部上下文

每个 MCP 都会增加模型可见工具，也会增加上下文成本。工具越多，模型越慢、越容易选错工具，也越容易触碰不该碰的外部系统。

flowchart LR
    Need["需要外部上下文"] --> Builtin{"内置工具够用?"}
    Builtin -->|够| Stop["不接 MCP"]
    Builtin -->|不够| OneTime{"只是一次性查资料?"}
    OneTime -->|是| Web["用 webfetch / search"]
    OneTime -->|否| MCP["配置 MCP"]
    MCP --> ReadOnly["先只读验证"]
    ReadOnly --> Scope["按权限 / agent 收窄"]
    Scope --> Write["再考虑写入型工具"]

    style Stop fill:#dcfce7,stroke:#22c55e
    style MCP fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Write fill:#fee2e2,stroke:#ef4444

1. 最小配置

MCP 配在 opencode.json / opencode.jsonc 的 mcp 字段下。每个 server 要有唯一名字，prompt 里也可以用这个名字指定工具。

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

临时不用时，不要删除配置，直接关掉：

{
  "mcp": {
    "context7": {
      "enabled": false
    }
  }
}

名字要短而清楚。context7、sentry、gh_grep 比 my-documentation-search-server 更容易在 prompt 里准确指定。

2. 本地和远程怎么选

本地 MCP 最少需要 type: "local" 和 command：

{
  "mcp": {
    "my-local": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

远程 MCP 最少需要 type: "remote" 和 url，可以加 headers、oauth 和 timeout。

3. 远程组织默认值

官方文档说明，组织可以通过 .well-known/opencode endpoint 提供默认 MCP server。这些 server 可能默认关闭，让用户按需启用。

本地配置可以覆盖远程默认值。例如组织提供了 jira，你可以在本地启用：

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

这类能力适合企业集中配置，但仍要遵守最小启用原则。

4. OAuth 和认证

OAuth（Open Authorization，开放授权）是一套让第三方应用安全访问账号资源的标准协议。你登录"用 GitHub 账号登录其他网站"看到的跳转流程就是它。OpenCode 用 OAuth 是为了不让你把 password / API key 写进配置——浏览器跳一下、授权一次，token 自动存到本机。

远程 MCP 可能需要认证。OpenCode 会在收到 401 时启动 OAuth flow（让浏览器打开授权页，用户登录后回跳并发回 token），并在 server 支持它的情况下使用 Dynamic Client Registration（RFC 7591，让 OpenCode 自己向 OAuth server 注册 client，不用你提前去 server 后台手动建 client_id）。认证 token 会存到：

~/.local/share/opencode/mcp-auth.json

常用命令：

opencode mcp list
opencode mcp auth <server-name>
opencode mcp logout <server-name>
opencode mcp auth list
opencode mcp debug <server-name>

mcp auth 会打开浏览器授权；mcp debug 会检查当前认证状态、HTTP 连通性和 OAuth discovery flow。

如果 server 使用 API key，不走 OAuth，可以显式关闭自动 OAuth：

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

如果 provider 给了预注册 OAuth client，也可以配置 clientId、clientSecret 和 scope，同样优先走环境变量。

5. 控制工具可见范围

MCP 工具会进入 OpenCode 工具列表。官方文档里可以用 tools 关闭某个 MCP 或一组 MCP 工具：

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

MCP server tools 通常会以 server name 作为前缀注册。要关闭某个 server 的全部工具，可以使用类似：

{
  "tools": {
    "sentry_*": false
  }
}

tools 控制“工具是否可见”，permission 控制“可见工具被调用时 allow / ask / deny”。这两个不是同一层。

6. 按 agent 开放 MCP

如果 MCP 很多，推荐全局关掉，再给特定 agent 打开。思路是：

1. 在全局 tools 里禁用 MCP 工具。
2. 在特定 agent.tools 里启用需要的 MCP。

这比所有 agent 共享所有 MCP 更稳。比如 Sentry 工具只给排障 agent，文档搜索只给研究 agent，数据库只给只读诊断 agent。

7. 常见 MCP 示例

示例的重点不是把所有 MCP 常驻打开，而是先用一个只读问题验证认证、上下文和输出质量。

8. 验收清单

接入 MCP 后，至少检查：

• 只启用了真正高频的 1-3 个 MCP。
• opencode mcp list 能看到 server 状态。
• 需要 OAuth 的 server 已完成认证。
• API key 通过环境变量引用，不在配置文件里明文出现。
• 写入型外部工具默认 ask 或不可见。
• 大型 MCP 按 agent 打开，不给所有 agent。
• 工具名短，prompt 里容易指定。
• 出问题时能用 mcp debug 定位。

接下来去哪

官方资料

• OpenCode MCP servers：https://opencode.ai/docs/mcp-servers
• OpenCode Config：https://opencode.ai/docs/config
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Permissions：https://opencode.ai/docs/permissions