5. MCP 与扩展

这是什么：MCP（Model Context Protocol，模型上下文协议） = 一套让 AI 连接外部工具和数据源的通用约定，一个服务器接上，模型就多出一批可用工具。

为什么用：opencode 自带的是「读文件、跑命令」这些通用能力。想让它查监控报错、翻官方文档、读工单系统，就得一个个手写工具函数；而 MCP 让你换服务不用改代码。

如何用：本章先接一个远程 MCP 试手，再接本地 MCP，然后学会按需开关工具，最后看看插件与 Skills 还能加什么。

5.1 MCP 怎么工作

MCP 服务器（本地进程 or 远程 HTTP）
   ↓ 暴露一组「工具」
opencode 把这些工具塞进模型的可用清单
   ↓
模型想用的时候，发起一次调用
   ↓
结果回到对话里

关键点：工具自动可用，你不用写任何胶水代码。配置好服务器，它提供的工具就会和内置工具并排出现。

5.2 接一个远程 MCP

在 opencode.json 的 mcp 字段里加：

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

保存后执行 opencode mcp list，可以看到连接状态：

$ opencode mcp list
  context7  connected  (12 tools)

然后直接点名让它用：

配置一个 Cloudflare Worker 缓存 JSON 响应，缓存 5 分钟，用 context7 查文档

5.3 接一个本地 MCP

本地 MCP 是一个你启动的子进程，opencode 通过标准输入输出跟它对话：

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

保存后执行 opencode mcp list：

$ opencode mcp list
  mcp_everything  connected  (4 tools)

command 是一个数组：第一个是程序，后面是参数。cwd 可以指定工作目录，environment 传环境变量。

不想手写 JSON？让命令行带你：

opencode mcp add      # 交互式：选本地还是远程，一步步填

5.4 需要登录的 MCP（OAuth）

大部分远程 MCP 都走 OAuth（一种让你「点一下授权」而不是粘贴密钥的登录协议）。opencode 检测到 401 会自动发起流程，token 存到 ~/.local/share/opencode/mcp-auth.json。

opencode mcp auth sentry     # 打开浏览器完成授权
opencode mcp auth list       # 看哪些服务器能登录、登录了没
opencode mcp debug sentry    # 排查连不上 / 授权失败
opencode mcp logout sentry   # 删掉存的凭证

如果服务器用的是 API Key 而不是 OAuth，把自动检测关掉：

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

你会看到（示意）：

$ opencode mcp list
  my-server  connected  (8 tools)

5.5 工具太多怎么办

MCP 工具全都占上下文。GitHub 那类服务器动辄几十个工具，很容易把上下文窗口塞满。opencode 的工具名带服务器前缀（服务器名_工具名），所以能整片关掉：

{
  "mcp": {
    "my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp"] },
    "other-mcp": { "type": "local", "command": ["bun", "x", "other-mcp"] }
  },
  "tools": {
    "my-mcp_*": false,
    "other-mcp_*": false
  },
  "agent": {
    "researcher": {
      "permission": { "my-mcp_*": "allow" }
    }
  }
}

读法：全局把两个 MCP 都关掉，只给 researcher 这个 agent 开 my-mcp_*。想临时用单个工具也行："my-mcp_search": "ask"。

⚠️ 版本提示：这里同时出现了 tools 和 permission 两个字段——官方文档目前自相矛盾：agents 文档把 tools 标为 deprecated、改推 permission（allow/ask/deny），而 config 文档的示例仍在用 tools。上面照抄了官方 config 文档的写法。你手上的版本到底认哪个字段，用 opencode debug config 看实际生效的配置最保险。

生效后，模型在 researcher 会话里能看见 my-mcp 的工具，在别的会话里看不见：

$ opencode debug config
{
  "tools": { "my-mcp_*": false, "other-mcp_*": false },
  "agent": { "researcher": { "permission": { "my-mcp_*": "allow" } } }
}

5.6 除了 MCP 还能加什么

插件也能从 npm 装：

opencode plugin opencode-helicone-session
opencode plug @my-org/custom-plugin

你会看到（示意）：

  installed opencode-helicone-session
  added to opencode.json: "plugin": ["opencode-helicone-session"]

动手改

1. 用 opencode mcp add 接一个远程 MCP（比如 Context7），然后 opencode mcp list 确认状态是 connected。
2. 写一个本地 MCP 配置（"command": ["npx", "-y", "@modelcontextprotocol/server-everything"]），跑 opencode mcp list 确认 connected，再在提示词里点名让它用。
3. 装两个 MCP，把其中一个用 "tools": { "xxx_*": false } 关掉，对比一下模型选工具时的表现差异。

小结

• MCP = 通用协议，接上服务器模型就自动多一批工具，配置在 opencode.json 的 mcp 字段
• 两种类型："local"（command 数组启子进程）与 "remote"（url + headers）
• 认证走 opencode mcp auth <名字>，token 存 ~/.local/share/opencode/mcp-auth.json
• 工具名带服务器前缀，可用 tools / permission 按服务器或单个工具开关——MCP 工具很吃上下文，别乱装
• 插件、Skills、LSP、格式化器是另外四层扩展能力

下一章：综合练习 🐸