在 stable OpenCode 中连接 MCP，需要把 local 或 remote server 添加到 opencode.json 顶层 mcp 对象，完成所需认证，验证 server 与工具，并且只启用当前任务真正需要的能力。本文的配置结构以 OpenCode MCP server 官方文档为准。
MCP 是 Model Context Protocol（模型上下文协议）。在实际使用中，它允许 AI client 发现并调用 server 暴露的工具或数据。Local server 通常作为进程运行在同一环境，remote server 则通过网络 transport 访问。
本文只回答一个问题：怎样在 stable OpenCode 内配置 MCP servers。搜索结果中也可能出现名为 opencode-mcp 的第三方项目，它们把 OpenCode 暴露成 server 或 bridge。这些是不同产品，需要独立的信任和安全审查，其命令不属于本文。
下方配置结构已在 2026 年 8 月 26 日对照官方 stable 文档核验。本机 OpenCode 1.18.23 还成功加载了 opencode mcp --help 与 opencode debug --help。我们没有连接真实 MCP server、provider 或 OAuth 账户，因此这些内容仍是安全配置模板，不是对线上集成成功的声明。
连接 MCP server 前先检查什么
MCP 连接可能赋予 Agent 很有影响力的访问能力。在添加 JSON 前，先回答六个问题。
1. 你是否正在使用 stable OpenCode？
本文覆盖 stable opencode binary。OpenCode v2 是独立 beta，使用 opencode2，MCP 配置结构也不同。不要混用两套文档中的示例。
2. 谁在运营这个 server？
检查发布者、代码仓库、release 流程、文档以及预期网络目标。出现在公共目录中，或者名字看起来熟悉，都不能证明一个 server 官方、安全或兼容。
3. Server 能做什么？
列出它暴露的工具和数据。文件系统、shell、数据库、issue tracker 与生产 API 的风险完全不同。先选择能完成任务的最窄 server 与工具集合。
4. 它使用哪种 transport？
当前 MCP 官方规范包含 stdio 与 Streamable HTTP transport。Stable OpenCode 把进程型连接表示为 local，把 URL 型连接表示为 remote。协议支持某种 transport，并不能证明当前 OpenCode client 已实现所有协议选项；配置前必须确认 server 与当前 client 实际支持同一种 transport。
5. 它怎样认证？
Remote server 可能使用 OAuth 或 headers。即使 JSON 接受 headers，也不要把 token 提交进仓库、粘贴到文章、放进截图，或保存在共享配置中。使用当前受支持的 secret 或 OAuth 路径，并确认谁能够读取最终凭证。
6. 它会占用多少上下文和注意力？
MCP 工具定义会占用模型上下文。启用很多 servers 可能加入大量无关工具、增加选择歧义，并在真正工作开始前消耗上下文。Stable OpenCode 文档建议只启用当前任务需要的 servers 和 tools。
在 stable OpenCode 中配置 local MCP server
Local MCP server 会在 OpenCode 所在环境中作为进程启动。Stable 配置使用顶层 mcp 对象、type: "local"、command array 和 enabled。
下面是 schema 模板，不是可运行的 server 命令：
只有在受信任 server 的当前官方文档中找到准确 executable 与参数后，才能替换占位符。在某个无 secret 的 server 完成 smoke test 前，不要把模板变成可直接复制执行的命令。
Local server 需要验证什么
- OpenCode 读取了目标
opencode.json。 - OpenCode 实际使用的同一环境与 PATH 中存在该 executable。
- 命令能启动，并且不会意外下载或执行未经审查的 package。
- 进程使用预期 MCP transport，而不是只输出无关文字。
- 已了解它的工作目录、环境变量、文件系统权限和子进程权限。
- 停止 OpenCode 或禁用 server 后，没有留下意外进程。
command array 是一个执行边界。请把每个元素当作代码配置，而不是无害 metadata。
配置 remote MCP server
Remote server 使用 type: "remote" 与 URL。Stable OpenCode 还记录了可选 headers。
下面的无 secret 示例使用保留的 .invalid 域名，避免被误认为可用服务：
只有核验 server 运营方与当前官方 endpoint 后，才能替换 URL。检查拼写、scheme、redirect、证书行为、transport 支持、账号范围，以及每个工具可能接收的数据。
不要把认证 secret 写死在配置里
Stable 文档允许为 remote 连接配置 headers，但本文不会提供可以直接复制的 bearer token block。必须针对当前 OpenCode 版本和 server 认证设计，确认正确的安全注入方式。
不要把 bearer-token header 片段作为默认 secret 存储方案。应优先使用 server 支持的 OAuth 流程，或经过核验的安全 secret 注入方式；如果无法演示一种安全机制，就省略 header 配置。截图必须隐藏 token、authorization code、账号标识、私有 URL 与 callback 参数。
通过 OAuth 认证 remote server
Stable OpenCode 文档记录了 remote MCP OAuth，以及 list、auth、logout 和 debug 等 CLI 管理路径。
OpenCode 1.18.23 的 CLI 帮助已确认 MCP 管理入口存在，官方文档列出以下命令结构：
本机检查确认了命令组存在，但没有对真实 server 完成认证。如果你安装的 CLI 修改了参数或使用交互式选择器，请以当前帮助为准，不要保留过时语法。
安全 OAuth 流程应按下面顺序检查：
- 确认配置中的 server 名称与 URL。
- 从 stable OpenCode CLI 开始认证。
- 批准前阅读授权页面中的发布者、请求 scope、账号和 redirect。
- 返回 OpenCode，在不暴露 code 或 token 的情况下确认状态。
- 检查实际开放了哪些工具。
- 测试 logout，并确认撤销了哪个凭证或 session。
OAuth 流程成功，只能证明认证完成；它不能证明 server 值得信任、scope 足够小，或每个工具都适合当前项目。
验证连接并限制可用工具
JSON 能解析，不代表连接已经完整可用。
检查 server 状态
使用当前 stable MCP list 或 status 路径，记录 server 状态。对于 local server，检查进程是否持续运行以及是否报告协议错误；对于 remote server，区分 URL、transport、authentication、authorization 与 server 错误。
确认工具发现
打开一次性测试项目，检查 OpenCode 显示该 server 提供了哪些工具，并与 server 当前官方文档比较。意外出现文件系统、shell、write、delete 或管理工具，应该立即暂停审查，而不是当作额外福利。
限制启用范围
先只启用一个可信 server。如果 OpenCode 与 server 提供 tool-level 控制，只暴露本次测试需要的工具。准确权限结构会受版本和集成影响，必须来自当前 stable 文档，不能凭空猜 JSON。
运行无害测试
选择一个只读取非敏感测试数据、而且结果可观察的操作。第一次测试不要使用生产凭证、客户数据、破坏性工具或写入动作。在遵守环境日志与隐私规则的前提下，记录 OpenCode 发送了什么、server 返回了什么，以及 Agent 输出了什么。
观察上下文占用
比较 server 禁用与启用时的 session。观察工具目录和相关用量信息，不要声称存在通用 token 成本。如果当前任务不需要某个 server，就禁用它。
排查 OpenCode MCP 错误
从配置开始，依次检查 transport、认证、工具和上下文。一次同时改很多层，会让真正原因更难确定。
分享日志前先脱敏
MCP debug 输出可能包含 URL、账号标识、headers、工具参数、文件路径或返回数据。粘贴到 Issue、文章或支持渠道前，先删除 secret 和私有信息。脱敏本身也要检查；只遮住单词 token，不代表凭证值已经消失。
Stable OpenCode 与 v2 MCP 配置
本文使用 stable schema：
- binary：
opencode； - 配置：顶层
mcp； - server 状态：
enabled。
独立的 v2 beta 文档使用另一条版本轨道，包括：
- binary：
opencode2； - 配置路径：
mcp.servers； - server 状态：
disabled。
这些差异是警告，不是邀请用户混合字段。使用 v2 示例前，先确认 v2 是否仍为 beta，以及是否有行为已经进入 stable。所有配置示例必须始终只对应同一个 binary 和同一套文档。
OpenCode Skills 不是 MCP servers
OpenCode Skill 是通过 skill tool 加载的可复用 SKILL.md 指令包；MCP server 是暴露工具或数据的本地或远程进程。
Skill 用于教授一套可复用方法，MCP 用于连接实时外部能力。Skill 可以解释何时以及怎样使用 MCP 工具，但不应该存放工具 token，也不能假装已经建立 server 连接。单独的 OpenCode Skills 指南介绍 discovery 与 permission.skill 行为。
在 Agent.Space 中使用 OpenCode MCP
OpenCode 上游支持 MCP，不代表 Agent.Space 已提供相同的设置路径。托管环境可能在命令执行、网络、secret 存储、callback、权限、transport 和持久化方面存在差异。如果你还在比较本地、自托管与托管环境，先阅读如何在云端运行 OpenCode。
依赖 Agent.Space MCP 工作流前，请以当前产品界面和公开产品资料为准，确认是否提供 OpenCode MCP 配置、支持哪些连接与认证方式、会暴露哪些工具和权限，以及怎样禁用或移除 server。如果界面或公开资料没有展示这些控制，就把本文当成本地或自托管 OpenCode 教程，而不要视为已经确认的 Agent.Space 配置路径。
OpenCode MCP 配置检查表
在判断集成已经可用前，确认：
- 使用 stable
opencode，不是 betaopencode2； - 核验 server 发布者、当前文档、endpoint 或 executable，以及 transport；
- 使用 stable 顶层
mcp与当前enabled字段； - 不把真实 secrets 写进已提交 JSON、截图、日志或 Prompt；
- 只有检查发布者、账号、scope 与 redirect 后才完成 OAuth；
- 确认观察到的 server 与工具列表；
- 先用非敏感数据做无害测试；
- 禁用不需要的 servers 和 tools；
- 测试 logout、禁用和失败恢复；
- 分享 debug 输出前完成脱敏。
先配置一个可信 server。与一次加载大量工具相比，小而可观察的连接更容易保护，也更容易排错。如果真正需要的是持续保存的托管项目边界，请单独查看 Agent.Space Workspace。
下一步
先在一次性 stable OpenCode 项目中连接一个可信 MCP server，核对状态和工具列表，并且只启用任务需要的能力。如果 CLI 还没准备好，先看 OpenCode 安装教程；如果你需要的是可复用指令而非实时连接，请使用 OpenCode Skills。