跳至内容
OpenCode
app.header.homeapp.header.docs

MCP 服务器

添加本地和远程 MCP 工具。

您可以使用模型上下文协议（MCP）向 OpenCode 添加外部工具。OpenCode 支持本地和远程服务器。

添加后，MCP 工具将与内置工具一起自动提供给 LLM 使用。

注意事项

当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快累积起来。因此，我们建议您谨慎选择使用的 MCP 服务器。

某些 MCP 服务器，例如 GitHub MCP 服务器，往往会添加大量令牌，并且很容易超出上下文限制。

启用

您可以在 OpenCode 配置的 mcp 下定义 MCP 服务器。为每个 MCP 添加一个唯一名称。在向 LLM 提示时，您可以通过名称引用该 MCP。

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

您还可以通过将 enabled 设置为 false 来禁用服务器。如果您想在不从配置中删除服务器的情况下临时禁用它，这会很有用。

覆盖远程默认值

组织可以通过其 .well-known/opencode 端点提供默认 MCP 服务器。这些服务器可能默认禁用，允许用户选择他们需要的服务器。

要从您组织的远程配置中启用特定服务器，请将其添加到您的本地配置中，并将 enabled: true

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

您的本地配置值将覆盖远程默认值。有关更多详细信息，请参阅配置优先级。

本地

通过在 MCP 对象中将 type 设置为 "local" 来添加本地 MCP 服务器。

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

命令是本地 MCP 服务器的启动方式。您还可以传入环境变量列表。

例如，以下是添加测试 @modelcontextprotocol/server-everything MCP 服务器的方法。

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

要使用它，我可以在提示中添加 use the mcp_everything tool。

use the mcp_everything tool to add the number 3 and 4

选项

以下是配置本地 MCP 服务器的所有选项。

选项类型 (Type)必需描述
类型字符串是MCP 服务器连接类型，必须是 "local"。
command数组是运行 MCP 服务器的命令和参数。
环境变量对象运行服务器时要设置的环境变量。
已启用布尔值在启动时启用或禁用 MCP 服务器。
超时数字从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

远程

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

opencode.json
{
  "$schema": "https://opencode.ac.cn/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

url 是远程 MCP 服务器的 URL，您可以通过 headers 选项传入请求头列表。

选项

选项类型 (Type)必需描述
类型字符串是MCP 服务器连接类型，必须是 "remote"。
网址字符串是远程 MCP 服务器的 URL。
已启用布尔值在启动时启用或禁用 MCP 服务器。
请求头对象要随请求发送的请求头。
OAuth对象OAuth 认证配置。请参阅下面的 OAuth 部分。
超时数字从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

OAuth

OpenCode 自动处理远程 MCP 服务器的 OAuth 认证。当服务器需要认证时，OpenCode 将：

  1. 检测到 401 响应并启动 OAuth 流程
  2. 如果服务器支持，则使用 动态客户端注册 (RFC 7591)
  3. 安全存储令牌以供将来请求

自动

对于大多数启用 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器

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

如果服务器需要认证，OpenCode 会在您首次尝试使用它时提示您进行认证。如果不需要，您可以使用 opencode mcp auth <server-name> 手动触发流程。

预注册

如果您有来自 MCP 服务器提供商的客户端凭据，您可以配置它们

opencode.json
{
  "$schema": "https://opencode.ac.cn/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"
      }
    }
  }
}

正在认证

您可以手动触发认证或管理凭据。

使用特定 MCP 服务器进行认证

终端窗口
opencode mcp auth my-oauth-server

列出所有 MCP 服务器及其认证状态

终端窗口
opencode mcp list

删除存储的凭据

终端窗口
opencode mcp logout my-oauth-server

mcp auth 命令将打开您的浏览器进行授权。授权后，OpenCode 会将令牌安全地存储在 ~/.local/share/opencode/mcp-auth.json 中。

禁用 OAuth

如果您想禁用服务器的自动 OAuth（例如，对于使用 API 密钥而非 OAuth 的服务器），请将 oauth 设置为 false

opencode.json
{
  "$schema": "https://opencode.ac.cn/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 选项

选项类型 (Type)描述
OAuth对象 | falseOAuth 配置对象，或 false 以禁用 OAuth 自动检测。
客户端 ID字符串OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
客户端密钥字符串OAuth 客户端密钥，如果授权服务器需要。
范围字符串授权期间请求的 OAuth 范围。

调试

如果远程 MCP 服务器认证失败，您可以通过以下方式诊断问题：

终端窗口
# View auth status for all OAuth-capable servers
opencode mcp auth list


# Debug connection and OAuth flow for a specific server
opencode mcp debug my-oauth-server

mcp debug 命令显示当前的认证状态，测试 HTTP 连接性，并尝试 OAuth 发现流程。

管理

您的 MCP 在 OpenCode 中作为工具提供，与内置工具一起。因此，您可以像管理其他工具一样通过 OpenCode 配置来管理它们。

全局

这意味着您可以全局启用或禁用它们。

opencode.json
{
  "$schema": "https://opencode.ac.cn/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 模式来禁用所有匹配的 MCP。

opencode.json
{
  "$schema": "https://opencode.ac.cn/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
  }
}

这里我们使用 glob 模式 my-mcp* 来禁用所有 MCP。

按代理

如果您有大量 MCP 服务器，您可能希望仅按代理启用它们并全局禁用它们。要做到这一点：

  1. 将其作为工具全局禁用。
  2. 在您的代理配置中，将 MCP 服务器作为工具启用。
opencode.json
{
  "$schema": "https://opencode.ac.cn/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 模式

glob 模式使用简单的正则表达式 glob 模式

  • * 匹配零个或多个任意字符（例如，"my-mcp*" 匹配 my-mcp_search、my-mcp_list 等）
  • ? 匹配正好一个字符
  • 所有其他字符都按字面匹配

示例

以下是一些常见 MCP 服务器的示例。如果您想记录其他服务器，可以提交 PR。

Sentry

添加 Sentry MCP 服务器以与您的 Sentry 项目和问题进行交互。

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

添加配置后，使用 Sentry 进行认证

终端窗口
opencode mcp auth sentry

这将打开一个浏览器窗口，完成 OAuth 流程并将 OpenCode 连接到您的 Sentry 账户。

认证后，您可以在提示中使用 Sentry 工具查询问题、项目和错误数据。

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

Context7

添加 Context7 MCP 服务器以搜索文档。

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

如果您已注册免费账户，您可以使用您的 API 密钥并获得更高的速率限制。

opencode.json
{
  "$schema": "https://opencode.ac.cn/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

这里我们假设您已设置 CONTEXT7_API_KEY 环境变量。

在您的提示中添加 use context7 以使用 Context7 MCP 服务器。

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.

Vercel 的 Grep

添加 Vercel 的 Grep MCP 服务器，以在 GitHub 上搜索代码片段。

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

由于我们将 MCP 服务器命名为 gh_grep，您可以在提示中添加 use the gh_grep tool 以让代理使用它。

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.