进阶 opencode.ai 2026-11-11 16:13:22 · 18 阅读

第22章 MCP 服务器

MCP 服务器 OpenCode 连接 Model Context Protocol(MCP)服务器,并暴露工具、提示词、资源和指令等功能。由于 MCP 工具会消耗模型上下文,请仅添加所需的服务器。

在需要使用该服务器的项目中添加远程服务器,然后检查其连接状态: 终端 `opencode mcp add context7 --url https://mcp.context7.com/mcp` `opencode mcp list`

该命令会将服务器写入项目配置。添加 `--global` 参数可使其在所有项目中可用: 终端 `opencode mcp add context7 --global --url https://mcp.context7.com/mcp`

远程服务器默认使用 OAuth。如果列表显示“需要认证”,请打开 OpenCode,运行 `/mcps`,选择该服务器并登录。已连接的服务器即可供智能体使用: ✓ context7 已连接

要手动配置服务器,请在 `mcp.servers` 下为其指定一个唯一名称。V2 不会将服务器名称直接放在 `mcp` 下。 `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "my-server": { "type": "local", "command": ["npx", "-y", "example-mcp-server"], }, }, }, } ```

服务器会自动连接。使用 `disabled` 字段(而非 `enabled`)来配置但禁用某个服务器,使其保持不连接状态: JSONC ```json { "mcp": { "servers": { "my-server": { "type": "local", "command": ["npx", "-y", "example-mcp-server"], "disabled": true, }, }, }, } ```

优先级较高的项目配置会用同名条目完全覆盖服务器对象。若需分别连接不同服务器或账号,请使用不同的名称;否则,必须在覆盖配置中重复所有必填字段: `opencode.jsonc` ```json { "mcp": { "servers": { "my-server": { "type": "remote", "url": "https://mcp.example.com/mcp", }, }, }, } ```

本地服务器是指 OpenCode 通过 MCP stdio 传输协议启动的命令。使用 `--` 后跟命令来添加一个: 终端 `opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything`

通过重复的 `--env` 标志传递环境变量: 终端 `opencode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything`

使用配置来处理其他进程选项,例如工作目录: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], "cwd": ".", "environment": { "LOG_LEVEL": "info", "MCP_API_KEY": "{env:MCP_API_KEY}", }, }, }, }, } ```

| 字段 | 必填 | 描述 | | :--- | :--- | :--- | | type | 是 | 必须为 "local"。 | | command | 是 | 可执行文件及其参数。 | | cwd | 否 | 进程目录。相对路径从工作区解析,这也是默认值。 | | environment | 否 | 添加到 OpenCode 继承进程环境中的字符串变量。 | | disabled | 否 | 为 true 时阻止连接。默认为 false。 | | codemode | 否 | 设为 false 以直接暴露工具,而非通过 Code Mode。默认为 true。 | | timeout | 否 | 每个服务器的超时覆盖设置。 | | protocol | 否 | legacy(默认)、auto 或 2026-07-28。参见协议版本。 | | pool | 否 | 在目录间共享一个连接。默认为 false。参见共享连接。 |

使用 `{env:NAME}` 进行环境变量替换。JSON 字符串中的 Shell 表达式(如 `$NAME`)不会被展开: JSONC ```json { "environment": { "MCP_API_KEY": "{env:MCP_API_KEY}", }, } ```

远程服务器使用 MCP Streamable HTTP 传输协议,需要绝对 URL: 终端 `opencode mcp add context7 --url https://mcp.context7.com/mcp`

通过重复的 `--header` 标志传递请求头。对 `{env:NAME}` 引用加引号,以便 Shell 原样写入: 终端 `opencode mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'`

使用配置处理其他选项。将密钥存储在环境变量中,而不是文件中: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "oauth": false, "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}", }, }, }, }, } ```

| 字段 | 必填 | 描述 | | :--- | :--- | :--- | | type | 是 | 必须为 "remote"。 | | url | 是 | 绝对的 Streamable HTTP 端点。 | | headers | 否 | 发送到端点的字符串 HTTP 头。 | | oauth | 否 | OAuth 设置,设为 false 可禁用 OAuth。 | | disabled | 否 | 为 true 时阻止连接。默认为 false。 | | codemode | 否 | 设为 false 以直接暴露工具,而非通过 Code Mode。默认为 true。 | | timeout | 否 | 每个服务器的超时覆盖设置。 | | protocol | 否 | legacy(默认)、auto 或 2026-07-28。参见协议版本。 | | pool | 否 | 在目录间共享一个连接。默认为 false。参见共享连接。 |

仅当服务器专门使用 API 密钥或其他头部凭据时,才使用 `oauth: false`: JSONC ```json { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:MCP_API_KEY}" }, } ```

除非 `oauth` 为 false,否则远程服务器会启用 OAuth。OpenCode 会发现授权服务器,通过 PKCE 登录并刷新令牌。凭据存储在项目配置之外。

大多数服务器只需 URL 即可: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", }, }, }, } ```

如果服务器需要认证,运行 `/mcps`,选择它并在浏览器中完成授权。CLI 也可以启动相同流程: 终端 `opencode mcp auth sentry`

当 OpenCode 通过 SSH、容器或远程服务器运行时,登录后浏览器无法访问 OpenCode,会显示一个加载失败的页面。从地址栏复制该页面的 URL,并粘贴到登录提示中: `http://127.0.0.1:52817/callback?code=...&state=...`

当 OpenCode 等待浏览器时,此提示会出现在 `/mcps`、`opencode mcp auth` 以及桌面和 Web 应用的登录对话框中。

OpenCode 使用首个适用方法向授权服务器标识自身:

| 方法 | 使用场景 | | :--- | :--- | | 预注册客户端 | 配置了 `oauth.client_id`。 | | 客户端 ID 元数据文档 (CIMD) | 授权服务器支持 CIMD 和公共客户端,且未设置 `oauth.redirect_uri`。 | | 动态客户端注册 (DCR) | 上述条件均不满足。OpenCode 注册客户端并在后续登录中重用。 |

授权服务器通过其元数据选择加入 CIMD: JSON ```json { "issuer": "https://auth.example.com", "client_id_metadata_document_supported": true, "token_endpoint_auth_methods_supported": ["none"] } ```

使用 CIMD 时,OpenCode 发送其元数据文档 URL 作为 `client_id` 并跳过注册: `https://opencode.ai/oauth/opencode/client.json`

该文档允许这些不带端口的回环重定向: `http://127.0.0.1/callback` `http://localhost/callback` `http://127.0.0.1/mcp/oauth/callback`(用于旧版客户端)

根据 RFC 8252 的要求,授权服务器接受这些重定向的任何回环端口,因此 `callback_port` 可与 CIMD 配合使用。自定义 `redirect_uri` 不可以,因此 OpenCode 回退到 DCR。

如果授权服务器既不支持 CIMD 也不支持 DCR,请配置预注册客户端。

当提供给您客户端凭据时,请使用 V2 的 snake_case OAuth 字段: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "company-tools": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": { "client_id": "{env:MCP_CLIENT_ID}", "client_secret": "{env:MCP_CLIENT_SECRET}", "scope": "tools:read tools:execute", "callback_port": 19876, "redirect_uri": "http://127.0.0.1:19876/callback", }, }, }, }, } ```

| 字段 | 描述 | | :--- | :--- | | client_id | 预注册客户端 ID。优先级高于 CIMD 和 DCR。 | | client_secret | 机密客户端的密钥,在令牌请求体中发送。公共客户端可省略。 | | scope | 空格分隔的授权范围。默认为服务器拒绝未认证请求时指定的范围。 | | callback_port | 本地回调端口(1 到 65535)。默认为 redirect_uri 端口,若未设置则为可用的临时端口。 | | redirect_uri | 预注册的回环 URI,其路径和端口到达本地回调监听器。设置此项会禁用 CIMD。 | | auth_server_metadata_url | 授权服务器的 OAuth 或 OpenID Connect 元数据文档 URL。当 MCP 服务器未发布指定其授权服务器的保护资源元数据时设置此项。 |

如需重新登录或切换账号,请删除已存储的 OAuth 凭据: 终端 `opencode mcp logout sentry`

超时时间单位为正整数毫秒。在 `mcp.timeout` 下设置默认值;服务器的 `timeout` 对象会覆盖匹配的默认值。 `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "timeout": { "startup": 45000, "catalog": 30000, "execution": 600000, }, "servers": { "slow-tools": { "type": "remote", "url": "https://mcp.example.com/mcp", "timeout": { "catalog": 60000, }, }, }, }, } ```

| 超时类型 | 默认值 | 适用范围 | | :--- | :--- | :--- | | startup | 30 秒 | 传输连接和服务器初始化。 | | catalog | 30 秒 | 列出工具、提示词、资源和资源模板。 | | execution | 12 小时 | 工具调用、提示词获取和资源读取。 |

默认情况下,OpenCode 使用经典 MCP initialize 握手开启所有服务器。设置服务器的 `protocol` 以与基于 2026-07-28 修订版构建的服务器通信: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "modern": { "type": "remote", "url": "https://mcp.example.com/mcp", "protocol": "auto", }, }, }, } ```

| 值 | 行为 | | :--- | :--- | | legacy | 默认。发送 initialize 并使用 2025-11-25 及以前的协议修订版。 | | auto | 探测 2026-07-28 修订版的 `server/discover`,若服务器不支持则回退到 legacy。 | | 2026-07-28 | 要求 2026-07-28 修订版。与旧服务器的连接会失败。 |

探测本地 legacy 服务器会增加一个短生命周期的额外进程,且当服务器忽略未知请求时可能等待直到启动超时,因此请仅将 `auto` 限制在需要的服务器上。

一个 OpenCode 服务器可以打开多个目录,每个目录都独立连接到所有 MCP 服务器。将 `pool` 设为 true 可让具有相同服务器设置的目录共享一个连接和一个工具列表: `opencode.jsonc` ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "cloudflare": { "type": "remote", "url": "https://mcp.cloudflare.com/mcp", "pool": true, }, }, }, } ```

仅基于 2026-07-28 修订版的连接可被共享。设置 `pool` 后,未设置的 `protocol` 意味着 `auto`。若服务器以较旧修订版应答,或设置为 `legacy`,则每个目录保留一个连接。

仅当所有改变连接的因素都匹配时,目录才共享连接:远程服务器的 URL、头、OAuth 设置及登录账号;本地服务器的命令、工作目录和环境。超时和协议也必须匹配。服务器名称无需匹配,但登录按名称存储,因此 OAuth 服务器仅在相同名称下共享。

本地服务器仅在本机目录间共享,不在工作区内共享。跨项目共享需要固定的 `cwd`(如 "~")。若无固定值,它将在每个项目文件夹中运行,导致每个项目拥有自己的连接,OpenCode 会记录警告。

共享连接没有根目录。当工具请求输入时,请求出现在调用它的目录中。

一旦使用连接的最后目录关闭或断开服务器连接,该连接随即关闭。

OpenCode 将工具命名为 `_`。它将字母、数字、`_` 和 `-` 以外的字符替换为 `_`: 服务器: context 7 工具: resolve.library/id 名称: context_7_resolve_library_id

MCP 提示词变为名为 `:` 的命令,采用相同的规范化。例如: `/context_7:find_docs`

命令文本按顺序填充提示词参数。用空格分隔,包含空格的值需加引号: `/context_7:find_docs react "server components"`

选择规范化后仍保持唯一的简短服务器名称。在默认 Code Mode 下,工具按规范化服务器名称分组: `tools.context_7.resolve_library_id(...)`

Code Mode 是默认设置。当服务器的工具必须保留在提供方的原生工具列表中时,将 `codemode` 设为 false: JSONC ```json { "mcp": { "servers": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "codemode": false, }, }, }, } ```

使用权限操作在不断开服务器连接的情况下隐藏或拒绝工具。匹配规范化的 `_` 名称: JSONC ```json { "permissions": [ { "action": "context7_*", "resource": "*", "effect": "deny", }, ], } ```

智能体通过两个内置工具 `list_mcp_resources` 和 `read_mcp_resource` 读取 MCP 资源。使用以下权限操作控制它们:

| 操作 | 资源 | | :--- | :--- | | opencode_list_mcp_resources | 服务器名称。 | | opencode_read_mcp_resource | `:` |

例如,允许从 docs 服务器读取所有资源: JSONC ```json { "permissions": [ { "action": "opencode_read_mcp_resource", "resource": "docs:*", "effect": "allow", }, ], } ```

当服务器在初始化期间返回指令时,OpenCode 将其添加到系统提示词中: `` ` ` ` 创建新问题前请先搜索现有问题。` ` ` ``

对于使用 Code Mode 的服务器,OpenCode 添加一行说明智能体在哪里找到该服务器的工具。

当智能体权限拒绝服务器所有工具,或拒绝使用 Code Mode 服务器的 execute 权限时,会省略该服务器的指令。

服务器可通过 MCP 引导(elicitation)在调用期间请求输入。OpenCode 将请求显示为表单,对于 URL 请求则显示为打开链接: `sentry 正在请求输入`

关闭表单会取消该请求。

对于代表会话执行的调用,OpenCode 在 `CallToolRequest.params._meta["ai.opencode/sessionID"]` 中发送会话 ID。这适用于通过 stdio 和 Streamable HTTP 的直接工具和 Code Mode: JSON ```json { "method": "tools/call", "params": { "name": "lookup", "arguments": { "query": "example" }, "_meta": { "ai.opencode/sessionID": "ses_..." } } } ```

该 ID 是请求元数据,而非工具参数,因此不出现在模型可见的模式中。将其视为不透明的关联值:

| 规则 | 行为 | | :--- | :--- | | 身份 | 标识发起的 OpenCode 会话,而非 MCP 传输会话。 | | 存在性 | 在没有会话上下文的调用中可能缺失。 | | 安全性 | 不要仅凭此值进行身份验证或授权。 | | 隐私 | 远程服务器接收原始 ID,可能会记录或保留它。 |

从任意项目列出服务器及其当前连接状态: 终端 `opencode mcp list`

在 OpenCode 中使用 `/mcps` 查看、连接、断开或认证服务器。使用 CLI 添加服务器并管理 OAuth 凭据: 终端 `opencode mcp add sentry --url https://mcp.sentry.dev/mcp` `opencode mcp auth sentry` `opencode mcp logout sentry`

运行不带名称的 `opencode mcp auth` 可从支持 OAuth 的服务器中选择: 终端 `opencode mcp auth`

要移除服务器,请从添加它的地方(项目或全局配置)删除其条目: JSONC ```json { "mcp": { "servers": {}, }, } ```

在 `/mcps` 中断开服务器连接不会更改配置。直接编辑配置以设置 OAuth 客户端、超时、工作目录,或保持服务器断开连接: JSONC ```json { "mcp": { "servers": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "disabled": true, }, }, }, } ```

评论 (0)