OpenCode MCP 配置教程：7 步接入本地与远程服务器

本页只解决 OpenCode MCP 的独立搜索意图：如何添加、鉴权、验证、限制和排错外部工具。通用安装继续由部署页负责，本地模型由 Ollama 页负责，会话文件由 session storage 页负责。清晰的关键词边界能避免配置教程与已有安装页面互相竞争。

下文示例依据当前 OpenCode 官方 schema 与 CLI。MCP 提供方可以独立修改 URL、包名、权限范围和登录方式，因此团队采用前必须回到服务器所有者的官方文档核对。不要因为某个目录站列出一条命令，就在包含密钥或生产代码的仓库直接运行。

本地服务器是 OpenCode 启动的子进程，适合可信 CLI 包、需要本地文件或必须留在工作站内的工具。它是否稳定取决于运行时、包管理器、工作目录、环境变量和系统权限。

远程服务器是 HTTP 端点，适合文档检索、错误监控或托管数据库等共享服务，但会增加网络和鉴权依赖。应按提供方支持的安装方式选择传输，而不是先偏好某种 JSON 写法。

OpenCode 会合并配置来源，而不是用一个文件完全替换另一个文件。官方当前优先级从组织远程默认、全局配置、自定义配置、项目 opencode.json、.opencode 目录、内联配置，到最高优先级的托管设置。后加载来源只覆盖冲突字段，其他字段继续合并。

跨项目使用的工具放在 ~/.config/opencode/opencode.json，项目专用工具放在仓库根目录 opencode.json。项目配置可以随代码审查，但密钥仍应进入环境变量或 OAuth 流程，不能提交到 Git。

每个服务器使用稳定、可读的名称。这个名称会用于提示词、工具前缀和按 Agent 规则。不要使用 server1 这类模糊名称；暂时不用但需要保留说明的服务器，可以设置 enabled: false。

本地 MCP 需要 type: "local" 和 command 数组。第一个元素是可执行文件，后续元素是参数。数组可以减少 shell 引号差异，也更容易审查实际启动的进程。只有服务器确实依赖目录时才设置 cwd，相对路径会从工作区解析。

把 npx -y 当作供应链执行决策，而不是无害复制。需要稳定时固定包版本，核对发布者和源码仓库，并先在不含敏感数据的目录测试。团队还应记录 Node/Bun 版本以及包是每次下载还是受控安装。

通过 environment 与环境变量替换传入密钥，不要写字面值。token 只给必要 scope。如果工具能写文件、改数据库或调用生产 API，应先使用沙箱或只读账号，并在放开写入前检查工具列表。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs_search": {
      "type": "local",
      "command": ["npx", "-y", "trusted-mcp-package"],
      "enabled": true,
      "environment": { "MCP_TOKEN": "{env:MCP_TOKEN}" }
    }
  }
}

示例包只能替换为 MCP 服务器所有者发布的准确官方命令。

远程 MCP 需要 type: "remote" 和 HTTPS URL。只有官方文档明确要求请求头鉴权时才使用 headers。OpenCode 支持在请求头值里引用环境变量，使仓库可以审查 header 名称而不会保存真实密钥。

对于支持 OAuth 的服务器，OpenCode 能在 401 后启动授权，在支持时尝试动态客户端注册，打开浏览器并保存 token。使用 opencode mcp auth <server-name> 主动登录，用 opencode mcp auth list 看状态，用 opencode mcp logout <server-name> 删除凭据。

如果提供方给出 client ID、secret 和 scopes，把它们放在 oauth 对象并引用环境变量。默认不要申请宽权限。只有提供方明确使用 API key 等机制时，才设置 oauth: false。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "monitoring": {
      "type": "remote",
      "url": "https://provider.example/mcp",
      "oauth": {}
    }
  }
}

第一次测试不要执行生产写入。先运行 opencode mcp list，确认服务器存在、连接健康且鉴权状态正确。OAuth 或网络失败时，用 opencode mcp debug <server-name> 检查 HTTP 路径与发现流程。

随后让 OpenCode 列出该服务器工具，或以明确服务器名发起只读查询，并和源系统直接结果对比。确认无误后再做一个低风险仓库任务，检查 Git diff 或外部审计日志。

可靠的验收记录应包含服务器名、包或 URL、运行时版本、鉴权方式、工具前缀、成功的只读提示词、超时与回滚命令。这样个人实验才可被其他开发者复现。

1. 确认提供方只使用服务器所有者的官方包、端点和鉴权说明。
2. 确定范围决定它属于全局、单项目还是单 Agent。
3. 只加一项使用唯一名称，一次只启用一个新服务器。
4. 安全提供凭据引用环境变量或 OAuth，绝不提交真实密钥。
5. 列出并调试运行 list，分别定位连接或 OAuth 故障。
6. 先做只读测试执行窄查询并与源系统结果对比。
7. 谨慎开放写入审计日志、diff 和回滚验证后再增加写权限。

opencode mcp list
opencode mcp auth <server-name>
opencode mcp debug <server-name>
opencode mcp logout <server-name>

每个 MCP 的工具说明都会占用上下文。几十个工具会挤压仓库代码和指令空间，多个大服务器甚至可能超过模型上下文上限。关闭不用的服务器，优先窄工具集，并比较接入前后的提示质量。

OpenCode 可以用模式在全局关闭匹配工具，再对某个 Agent 单独启用。这适合数据库或监控等专业工作流，不必让普通编码会话都携带它们。规则应匹配真实工具前缀，不能只猜服务器名。

MCP 访问不能替代 OpenCode 权限和提供方鉴权。只读凭据、开发环境、分支保护、审计日志和审批规则要一起使用。模型只能调用收到的工具，但工具仍携带 token 的全部权限。

分享日志或凭据前，请继续阅读 OpenCode 会话存储与隐私指南 ；如果 MCP 工具会与小上下文本地模型一起运行，再查看 OpenCode Ollama 指南 。

一次只改变一层。先证明本地命令或远程端点可用，再证明鉴权，再证明 OpenCode 能发现工具，最后才调整提示词和 Agent 规则。提供方不可用时反复改 JSON 只会产生误导。

本地服务器应在干净终端运行完全相同的命令；Windows 包装器读取 stderr 时显式使用 UTF-8。远程服务器先看官方状态和端点，再用 debug。排错中如果输出过密钥，应立即轮换。

Similarweb 显示 opencode figma mcp 与 opencode supabase mcp 有明确需求，但每个提供方的权限和部署方式不同。因此本页只解释共享的 OpenCode 层，不发布未经核验的专用 JSON。应先采用 Figma 或 Supabase 官方 MCP 说明，再执行本文的本地/远程、凭据、验收与上下文检查。

文档检索和监控通常适合作为第一个集成，因为只读结果容易验证。数据库、源码和设计工具同样有价值，但写权限会放大错误成本。应把发现与修改分开，并记录每个环境允许的提示词。

opencode github 的主要意图是导航，应由 GitHub 或官方项目页承接，而不是再做一篇竞争文章。只有能够提供经过核验的安装、scope 和回滚细节时，具体 GitHub MCP 才值得独立成页。

安装基础请返回 OpenCode 部署指南. ；官方配置优先级与 MCP 选项见下方来源。