跳转到内容
OpenCode
HomeDocs

MCP 服务器

添加本地和远程 MCP 工具。

你可以通过 Model Context Protocol（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程 MCP 服务器。

一旦添加完成，这些 MCP 工具会和内置工具一起自动提供给 LLM 使用。

注意事项

启用 MCP 服务器会往对话上下文里注入额外信息；如果工具很多，Token 消耗会迅速增加。因此建议只启用真正需要的 MCP 服务器。

某些 MCP 服务器（例如 GitHub MCP）往往会注入大量 Token，比较容易碰到上下文上限。

启用 MCP

在 OpenCode 配置 中的 mcp 字段下定义 MCP 服务器。每个 MCP 使用一个唯一名称，你可以在 Prompt 里通过这个名字来引用该 MCP。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

把 enabled 设为 false 可以暂时禁用某个服务器，而无需删掉配置。

覆盖远程默认配置

组织可以通过 .well-known/opencode 端点下发默认 MCP 服务器配置，这些服务器通常默认是禁用的，需要用户显式启用。

如果想启用远程配置里某个名为 jira 的 MCP，可以在本地配置中写：

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

本地配置会覆盖远程默认值。更多说明见 配置优先级。

本地 MCP

在 mcp 配置对象中，将 type 设置为 "local" 来添加本地 MCP 服务器：

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // 或 ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

command 是启动本地 MCP 服务器的命令；可以通过 environment 传入环境变量。

例如添加测试用 MCP 服务器 @modelcontextprotocol/server-everything：

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

然后在 Prompt 中写：

use the mcp_everything tool to add the number 3 and 4

本地 MCP 参数

字段类型必填说明
typeString是MCP 连接类型，必须为 "local"
commandArray是启动 MCP 服务器的命令及参数
environmentObject否启动服务器时附加的环境变量
enabledBoolean否是否在启动时启用该 MCP 服务器
timeoutNumber否获取 MCP 工具列表时的超时时间（毫秒），默认 5000（5 秒）

远程 MCP

将 type 设置为 "remote" 来添加远程 MCP 服务器：

opencode.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"
      }
    }
  }
}

url 是远程 MCP 服务器地址，headers 可用来传递认证信息等 HTTP 头。

远程 MCP 参数

字段类型必填说明
typeString是MCP 连接类型，必须为 "remote"
urlString是远程 MCP 服务器 URL
enabledBoolean否是否在启动时启用
headersObject否请求附加的 HTTP 头
oauthObject否OAuth 配置，详见 OAuth 小节
timeoutNumber否获取工具列表时的超时时间（毫秒），默认 5000（5 秒）

OAuth

OpenCode 会自动为远程 MCP 服务器处理 OAuth 认证：

  1. 检测到 401 响应后，自动发起 OAuth 流程
  2. 若服务器支持，会使用 Dynamic Client Registration (RFC 7591)
  3. 将 Token 安全地存储，以供后续请求使用

自动模式

对于大多数支持 OAuth 的服务器，你无需特殊配置，只需写：

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

如果服务器需要认证，首次使用该服务器时 OpenCode 会提示你登录；也可以手动运行 opencode mcp auth <server-name> 来触发认证。

预注册客户端

如果你已经从提供方拿到了客户端凭据，可以显式配置：

opencode.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"
      }
    }
  }
}

手动认证与管理

你可以手动触发认证或管理凭据：

Terminal window
# 为指定 MCP 服务器发起 OAuth 认证
opencode mcp auth my-oauth-server


# 查看所有 MCP 及其认证状态
opencode mcp list


# 移除指定服务器的凭据
opencode mcp logout my-oauth-server

mcp auth 会打开浏览器完成授权，完成后 Token 会被保存到 ~/.local/share/opencode/mcp-auth.json。

禁用 OAuth

如果你希望禁用某个服务器的自动 OAuth（比如只用 API Key），可以将 oauth 设为 false：

opencode.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 配置字段

字段类型说明
oauthObject | falseOAuth 配置对象，或设为 false 明确禁用自动 OAuth 检测
clientIdStringOAuth Client ID；如未设置，会尝试动态客户端注册
clientSecretStringOAuth Client Secret，如授权服务器要求
scopeString请求授权时使用的 Scope

调试

如远程 MCP 认证失败，可以使用：

Terminal window
# 查看所有支持 OAuth 的服务器及其认证状态
opencode mcp auth list


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

mcp debug 会展示当前认证状态、HTTP 连通性测试结果以及 OAuth 探测流程。

管理 MCP

所有 MCP 工具会和内置工具一起对外暴露，因此你可以像管理普通工具一样，在配置中控制 MCP 工具的启用状态。

全局开关

例如，可以在配置中全局禁用某些 MCP：

opencode.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 模式一次性禁用多台服务器：

opencode.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
  }
}

上例中，my-mcp* 会匹配所有以 my-mcp 开头的 MCP 工具。

按 Agent 控制

如果你配置了大量 MCP，通常会希望默认禁用，只在特定 Agent 上启用。做法是：

  1. 在全局工具配置中将其禁用
  2. 在对应 Agent 配置 中启用该 MCP 工具
opencode.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 模式说明

符号含义
*匹配任意长度的任意字符（例如 "my-mcp*" 会匹配 my-mcp_search、my-mcp_list）
?匹配任意单个字符

示例

下面是几个常见 MCP 服务器的配置示例，如果你想补充其它服务器，欢迎提 PR。

Sentry

添加 Sentry MCP 服务器 以便在对话中访问 Sentry 项目和 Issue：

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

配置完成后，先进行认证：

Terminal window
opencode mcp auth sentry

成功后，你就可以在 Prompt 中使用 Sentry 相关工具，例如：

Show me the latest unresolved issues in my project. use sentry

Context7

添加 Context7 MCP 以检索文档：

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

如果你注册了账号并拿到了 API Key，可以通过 Header 传入：

opencode.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}"
      }
    }
  }
}

然后在 Prompt 中使用：

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

也可以在 AGENTS.md 里写：

AGENTS.md
When you need to search docs, use `context7` tools.

Grep by Vercel

添加 Grep by Vercel MCP 以从 GitHub 搜索代码片段：

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

由于服务器名为 gh_grep，可以在 Prompt 中写：

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

也可以在 AGENTS.md 里加入提示：

AGENTS.md
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.