连接 MCP 服务器

在运行时配置的 mcp 下，以唯一名称定义服务器。连接后工具与内置工具一起提供给模型；服务器名称也是提示中指定工具来源的线索。

本地进程

本地配置的 type 为 local，command 是可执行命令及参数数组。可选 cwd 相对工作区解析，environment 为进程设置变量。

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

这是官方测试服务器示例，运行时可能下载并启动包，不是仅注册静态名称。实际接入应换成需要的服务器和启动参数。

远程服务

远程配置使用 type: "remote" 与 url，可设置 headers、oauth、enabled 和 timeout。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs-service": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

示例域名需替换为真实服务。支持 OAuth 的远程服务器可以自动发现认证，预注册客户端和 API Key 方式见MCP 认证。

启停与超时

两种类型都支持 enabled: false，用于保留配置但禁用启动。timeout 均以毫秒计，默认 5000，指获取服务器工具的超时，不是所有工具调用统一的执行时限。

组织通过 .well-known/opencode 提供的默认服务器可以在本地启用；它是可覆盖的远程默认，与管理员托管设置不同。

工具权限与角色

工具名带服务器前缀，可按 servername_* 匹配。MCP 页仍用旧 tools 布尔配置演示控制，新配置采用 Permissions 页的 permission：

{
  "permission": {
    "docs-service_*": "ask"
  }
}

服务器启用、工具加载、单次调用获准是三个条件。也可在 Agent 权限中覆盖普通全局规则，让只有某个专门角色能够使用一组工具；具体规则顺序见权限。

已列出的远程示例

官方示例包括 Sentry 的 https://mcp.sentry.dev/mcp、Context7 的 https://mcp.context7.com/mcp 和 Grep by Vercel 的 https://mcp.grep.app。

Sentry 示例需完成 OAuth；Context7 可通过 CONTEXT7_API_KEY header 引用同名环境变量。是否需要账号、当前额度和可用性仍取决于服务，不将“示例可配置”写成所有用户均已授权。

控制上下文

MCP 的工具描述会占用上下文。官方特别提醒大型工具集合可能显著增加 token，甚至超过上下文限制。只启用任务需要的服务，或按角色控制工具集合，不要把一次性开启所有服务器作为默认流程。