为 OpenCode 挂载外部能力：MCP 服务器完全指南

oscar9992026-05-20 8:11

模型上下文协议（MCP）让 OpenCode 能够对接外部工具，无论是运行在本地的命令行程序，还是部署在远端的 HTTP 服务。一旦接入，这些 MCP 提供的工具就会和内置功能一样，自动出现在大语言模型的可用工具列表中，直接通过对话进行调用。

使用前的必要提醒

每个 MCP 服务器都会占用一部分上下文窗口。如果同时启用大量工具，很容易塞满 token 配额，尤其是一些返回数据量庞大的服务器。一个典型的例子是 GitHub MCP 服务器，它往往会拉入大量信息，稍不留神就可能超出上下文限制。因此，只开启真正需要的 MCP 服务器，是保持会话高效的关键原则。

启用 MCP 服务器

所有 MCP 服务器都在 opencode.json 配置文件的 mcp 字段下定义。每个服务器拥有一个独一无二的名字，后续在提示词中可以直接引用这个名字来调用工具。

plain 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true
    },
    "name-of-other-mcp-server": {
      // ...
    }
  }
}

如果只是暂时不想使用某个服务器，可以将其 enabled 设为 false，这样无需从配置中删除即可关闭。

覆盖组织远程默认值

一些团队会通过 /.well-known/opencode 端点提供默认的 MCP 服务器列表。这些远程预设可能是默认禁用的，供成员按需启用。要想激活某个来自组织远程配置的服务器，只需在本地配置中声明同名条目，并将 enabled 设为 true。本地配置的优先级会覆盖远程默认设置。

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

添加本地 MCP 服务器

将 type 设为 "local" 即可定义本地服务器。command 字段负责指定启动该服务器的命令和参数，还可通过 environment 对象注入环境变量。

plain 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

一个实际例子是接入官方的测试服务器 @modelcontextprotocol/server-everything：

plain 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

配置完成后，在提示词中写上"使用 mcp_everything 工具把 3 和 4 相加"，模型就会自动调用对应的运算工具。

本地 MCP 配置选项

选项 类型 必填 描述
type string 是 服务器连接类型，必须为 "local"。
command array 是 启动 MCP 服务器的命令及参数。
environment object 否 启动服务器时设置的环境变量。
enabled boolean 否 是否在启动时启用该服务器。
timeout number 否 从 MCP 服务器获取工具的等待时间（毫秒），默认 5000（5 秒）。

添加远程 MCP 服务器

将 type 设为 "remote"，并指定 url 即可接入远程 HTTP MCP 服务。同时可以携带自定义请求头，比如用于 API 密钥鉴权的 Authorization 头。

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

远程 MCP 配置选项

选项 类型 必填 描述
type string 是 服务器连接类型，必须为 "remote"。
url string 是 远程 MCP 服务器的 URL。
enabled boolean 否 是否在启动时启用该服务器。
headers object 否 请求时附加的自定义 HTTP 头。
oauth object 或 false 否 OAuth 认证配置，详见下文。设为 false 可关闭自动 OAuth。
timeout number 否 从 MCP 服务器获取工具的等待时间（毫秒），默认 5000（5 秒）。

OAuth 认证

远程 MCP 服务器如果需要授权，OpenCode 会自动处理 OAuth 流程。当服务端返回 401 状态码时，会触发以下动作：

  • 尝试使用动态客户端注册（RFC 7591，若服务器支持）
  • 安全存储令牌供后续请求使用

自动模式

绝大多数支持 OAuth 的 MCP 服务器无需额外配置，直接填写 URL 即可。若服务器要求授权，第一次尝试使用时会弹出认证提示；也可以手动执行 opencode mcp auth <服务器名> 来启动流程。

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

预注册客户端凭证

如果已经从服务方拿到了客户端 ID 和密钥，可以直接写入配置：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.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"
      }
    }
  }
}

凭证管理命令

手动管理认证状态可以使用以下终端命令：

  • 对指定服务器发起认证：opencode mcp auth my-oauth-server
  • 列出所有 MCP 服务器及认证状态：opencode mcp list
  • 移除已存储的凭证：opencode mcp logout my-oauth-server

执行 mcp auth 命令会打开系统浏览器进行授权，完成后令牌会安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

关闭自动 OAuth

对于使用 API 密钥而非 OAuth 的服务器，可将 oauth 设为 false 来禁用自动认证检测，同时仍可通过 headers 传递密钥：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

OAuth 选项细节

选项 类型 描述
oauth object 或 false OAuth 配置对象，设为 false 则禁用自动 OAuth 检测。
clientId string OAuth 客户端 ID。不提供时会尝试动态注册。
clientSecret string OAuth 客户端密钥，视授权服务器要求而定。
scope string 授权时请求的作用域。

调试连接问题

当远程 MCP 服务器认证失败时，可以使用调试命令定位问题：

bash 复制代码 
# 查看所有具备 OAuth 能力的服务器认证状态
opencode mcp auth list

# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 命令会显示当前认证状态、测试 HTTP 连通性，并尝试执行 OAuth 发现流程。

精细控制 MCP 工具

接入的 MCP 服务器会以工具形式出现在 OpenCode 中，与内置工具并列。可以在 tools 字段中像控制其他工具一样管理它们。

全局启用/禁用

直接对 MCP 服务器名进行全局开关设定：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false
  }
}

也可以使用 glob 通配符批量禁用所有匹配的服务器工具。例如，下面这条配置禁用了所有以 my-mcp 开头的 MCP 服务器：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false
  }
}

按代理（agent）启用

当 MCP 服务器数量较多时，更推荐的做法是全局禁用，只让特定的代理启用。首先在全局工具中将其关闭，然后在目标代理的配置里重新打开：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.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 模式

OpenCode 的 glob 支持简单规则：

  • * 匹配零个或多个任意字符（如 my-mcp* 能匹配 my-mcp_search、my-mcp_list 等）
  • ? 匹配恰好一个字符
  • 其他字符原样匹配

有一点需要特别留意：MCP 服务器注册工具时，工具名会带上服务器名称作为前缀。所以，要禁用某个服务器的全部工具，只需使用 "服务器名_*": false 即可。

常见 MCP 服务器示例

以下是一些常用服务器的具体配置，开发者也可以向文档仓库提交 PR 来补充更多案例。

Sentry

接入 Sentry MCP 服务器后，可以直接在对话中查询项目和问题数据。

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

配置好之后，运行 opencode mcp auth sentry 完成浏览器中的 OAuth 授权。接下来就能在提示词里使用 use sentry 要求模型获取最新未解决的 issue 等信息。

Context7

Context7 提供文档搜索能力，适合在需要查阅最新技术资料时调用。

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

如果已经注册了 Context7 的免费账户，还可以提供 API 密钥来获得更高的速率限额。下面的写法假设环境变量 CONTEXT7_API_KEY 已经设置好：

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

使用时在提示词中加入 use context7 即可，也可以在 AGENTS.md 中写入类似指令，让模型自动在需要时搜索文档。

Vercel 的 Grep

Grep 工具能够搜索 GitHub 上的公开代码片段，适合查找实际用例。

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

由于这里给它取名 gh_grep，提示词中可以使用 use the gh_grep tool 来让模型调用。类似的，也可以在 AGENTS.md 里指示模型在不熟悉某个用法时主动使用 gh_grep 搜索 GitHub 代码示例。

通过 MCP 机制，OpenCode 将外部工具与语言模型的交互变得极其顺畅。从本地脚本到需要 OAuth 授权的远程服务，只需一份简洁的 JSON 配置，所有工具就能像内置功能一样被大模型理解和调用。配合灵活的启用策略和 glob 控制，即使在多代理、多工具的复杂环境下，依然能够保持上下文的高效利用。

相关推荐
oscar9991 天前
OpenCode 的内置格式化
格式化·opencode
用户000453921161 天前
OpenAI Tasks API 的集成与使用
mcp
stereohomology1 天前
vibe coding效率高：一个新mcp server已经试运行尚可
大语言模型·mcp·traecn·glm5.1·why不coding
小白学鸿蒙1 天前
Funplay Unity MCP 接入 trae 实战
unity·游戏引擎·mcp
oscar9991 天前
OpenCode 的权限系统：让自动化在可控范围内运行
权限·opencode
optimistic_chen2 天前
【AI Agent 全栈开发】MCP
java·linux·运维·人工智能·ai编程·mcp
HIT_Weston2 天前
86、【Agent】【OpenCode】bash 工具提示词（完结）
人工智能·agent·opencode
程序员柒叔2 天前
OpenCode 一周动态-2026-W20
人工智能·github·copilot·agent·opencode
HIT_Weston2 天前
85、【Agent】【OpenCode】bash 工具提示词（HEREDOC）
人工智能·agent·opencode
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04用了半年 OpenRouter，我换到了 Ofox.ai — 两个 AI API 聚合平台的真实对比05Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07【AI】2026 年具身智能模型和世界模型总结08【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法09codex app每次打开重连5次Reconnecting问题解决10Codex 手机端连接教程：三分钟搞定，附完整步骤