OpenCode 通过 MCP（Model Context Protocol，模型上下文协议）连接代码仓库、文档检索、数据库、浏览器自动化和企业 API 等外部能力。MCP 服务器并非“配置成功即可万事大吉”，其连接方式、启动参数、权限范围、超时策略和启用数量，都会直接影响工具是否可见、调用是否准确以及长时间运行时是否稳定。
一、接入配置决定外部工具的能力边界
MCP 的核心价值，是让 OpenCode 使用统一协议发现并调用外部工具。服务器完成连接后，可以向智能体提供工具、提示词、指令或资源。不过，OpenCode 只能使用服务器实际公开且当前账号有权访问的能力。因此，同一个 MCP 服务在不同 URL、凭据、工作目录和权限范围下，可能呈现完全不同的工具集合。配置文件实际上定义了外部能力的入口与边界。
需要特别注意版本差异。按照 OpenCode V2 的MCP 服务器文档，服务器应使用唯一名称配置在 mcp.servers 下，默认自动连接；如需停用，应设置 disabled，而不是沿用旧版配置中的 enabled。直接复制旧教程可能导致字段不生效，排查时应先确认当前使用的 OpenCode 版本和对应配置结构。citeturn1view1
二、本地与远程服务器影响稳定性的方式不同
本地服务器更依赖运行环境
本地 MCP 服务器通常由 OpenCode 启动，并通过标准输入输出进行通信。其稳定性取决于命令路径、运行时版本、依赖包、工作目录和环境变量。如果 command 指向的程序不存在，或者 cwd 与服务器预期目录不一致，便可能出现启动失败、读取错误项目文件或工具列表为空等情况。
配置本地服务时，建议使用明确的命令参数并固定关键依赖版本，不要把交互式安装、临时下载或需要人工输入的步骤放入启动流程。涉及密钥时，可通过 {env:NAME} 引用环境变量。官方说明指出，JSON 字符串中的 $NAME 不会像 Shell 一样自动展开，因此变量写法错误也可能表现为鉴权失败。citeturn1view1
远程服务器更依赖网络与认证
远程 MCP 服务器使用 Streamable HTTP 连接，必须提供有效的绝对 URL。其能力扩展更适合团队服务和云端接口，但也增加了 DNS、代理、证书、网关限流和服务端状态等外部因素。URL 路径看似细微的差异，也可能导致连接到普通网页、旧接口或不兼容的协议端点。
如果服务通过 API Key 鉴权，应将凭据放入环境变量，再通过 headers 注入请求，避免把密钥直接写入项目配置并提交到仓库。对于只接受请求头凭据的服务，可以显式设置 oauth: false；支持 OAuth 的远程服务则可使用授权发现、PKCE 和令牌刷新机制。认证模式与服务端不匹配时，常见现象不是完全断开，而是能够建立连接却无法执行受保护工具。citeturn1view1
三、启用数量会影响工具选择与上下文成本
MCP 服务器提供的工具描述需要进入模型上下文。一次性启用多个功能庞大的服务器，会增加上下文占用，还可能出现工具名称和用途相近的情况，使模型更难稳定选择正确入口。OpenCode 的相关说明也建议只启用当前需要的服务器，因为工具数量过多可能快速消耗上下文空间。citeturn1view1turn1view2
更合理的做法是按任务拆分配置。例如，日常编码仅启用文档检索和代码搜索；排查线上问题时再启用监控平台；执行数据库任务时只开放限定范围的查询工具。每台服务器使用清晰且唯一的名称，也有助于模型和使用者区分不同环境、账号及数据源。
四、超时设置决定“慢调用”是否被误判为故障
MCP 调用通常包含启动连接、读取工具目录和执行工具三个阶段。三者耗时特征不同：本地进程首次启动可能较慢，远程目录获取会受到网络影响，而构建、浏览器测试或大范围检索可能需要更长执行时间。如果只设置一个过短的统一超时，正常任务也会被提前终止；设置过长则会让真正失效的连接长时间占用会话。
OpenCode V2 支持分别配置 startup、catalog 和 execution 超时，并允许单个服务器覆盖全局默认值。实践中应先记录失败发生在哪个阶段，再有针对性地调整，而不是盲目放大所有时间限制。高延迟服务可以获得更长的目录或执行时间，本地轻量服务则保持较短超时，以便快速暴露异常。citeturn1view1
五、配置优先级与权限控制容易制造隐性问题
OpenCode 配置可能来自组织默认配置、用户级配置和项目级配置。同名服务器在更高优先级配置中可能被整体替换，而不一定是逐字段合并。如果项目配置只重写了 URL，却遗漏原有请求头或认证参数，最终效果可能是服务器仍然存在，但能力目录发生变化或调用持续返回未授权。需要连接不同环境或不同账号时，采用不同服务器名称通常比复用同名配置更清晰。
权限应遵循最小化原则。文件系统服务只开放必要目录，数据库账号优先使用只读权限，远程 OAuth 只申请任务所需的 scope。这样不仅降低误操作风险，也能减少无关工具进入上下文。对于写文件、发布内容、修改工单或执行数据库变更等高影响操作，还应在服务端保留审计记录和必要的人工确认机制。
六、提升调用稳定性的排查顺序
- 先验证配置结构：确认字段属于当前 OpenCode 版本，服务器名称唯一，JSON 或 JSONC 语法正确。
- 再验证独立运行：本地服务先检查命令、依赖和工作目录，远程服务先检查端点、证书与网络连通性。
- 检查工具目录：确认服务器能够完成初始化，并返回预期的工具、提示词或资源列表。
- 核对认证权限：检查环境变量是否存在、请求头是否正确、OAuth 令牌是否有效，以及账号是否具备目标权限。
- 定位超时阶段：区分启动、目录获取和实际执行问题，再调整对应超时参数。
- 控制启用范围：暂时关闭无关服务器，排除工具冲突、上下文膨胀和外部依赖干扰。
- 逐个恢复连接：从最小可用配置开始，一次只增加一个服务器或一个参数，便于确定故障来源。
稳定的 MCP 接入不等于把超时调大或把所有服务器同时打开，而是让连接方式、认证策略、权限范围和任务需求保持一致。
总结
OpenCode 的外部工具扩展能力取决于 MCP 服务器公开了什么，而调用稳定性则取决于这些能力如何被连接和管理。正确区分本地与远程服务、使用符合版本的配置结构、妥善处理环境变量和 OAuth、按阶段设置超时、控制启用数量并遵循最小权限原则，可以显著减少工具不可见、鉴权失败、调用中断和选择混乱等问题。将 MCP 配置视为一套需要版本管理、分层验证和持续维护的基础设施，才能让外部工具真正成为可靠的开发能力，而不是新的不确定因素。
