MCP 服务器

添加本地和远程 MCP 工具。

你可以使用 Model Context Protocol (MCP) 向 OpenCode 添加外部工具。OpenCode 支持本地和远程服务器。

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

注意事项 Caveats

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

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

启用 Enable

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

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

你也可以通过将 enabled 设置为 false 来禁用服务器。这在你想要暂时禁用服务器而不从配置中将其删除时很有用。

覆盖远程默认值 Overriding remote defaults

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

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

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

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

本地 Local

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

{
  "$schema": "https://opencode.ai/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 服务器：

{
  "$schema": "https://opencode.ai/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

选项 Options

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

选项 Option	类型 Type	必填 Required	描述 Description
`type`	String	Y	MCP 服务器连接的类型，必须为 `"local"`。
`command`	Array	Y	运行 MCP 服务器的命令和参数。
`environment`	Object		运行服务器时要设置的环境变量。
`enabled`	Boolean		在启动时启用或禁用 MCP 服务器。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

远程 Remote

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

{
  "$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 服务器的 URL，通过 headers 选项，你可以传递一个头部列表。

选项 Options

选项 Option	类型 Type	必填 Required	描述 Description
`type`	String	Y	MCP 服务器连接类型，必须为 `"remote"`。
`url`	String	Y	远程 MCP 服务器的 URL。
`enabled`	Boolean		在启动时启用或禁用 MCP 服务器。
`headers`	Object		随请求发送的头部。
`oauth`	Object		OAuth 身份验证配置。参见下面的 OAuth 部分。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

OAuth

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

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

自动 Automatic

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

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

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

预注册 Pre-registered

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

{
  "$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"
      }
    }
  }
}

身份验证 Authenticating

你可以手动触发身份验证或管理凭据。

使用特定 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 Disabling OAuth

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

{
  "$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 选项 OAuth Options

选项 Option	类型 Type	描述 Description
`oauth`	Object \| false	OAuth 配置对象，或 `false` 以禁用 OAuth 自动检测。
`clientId`	String	OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
`clientSecret`	String	OAuth 客户端密钥，如果授权服务器需要。
`scope`	String	授权期间请求的 OAuth 范围。

调试 Debugging

如果远程 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 发现流程。

管理 Manage

你的 MCP 可作为 OpenCode 中的工具使用，与内置工具并列。因此，你可以像任何其他工具一样通过 OpenCode 配置来管理它们。

全局 Global

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

{
  "$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 模式禁用所有匹配的 MCP。

{
  "$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
  }
}

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

每个智能体 Per agent

如果你有大量的 MCP 服务器，你可能希望仅为每个智能体启用它们，并在全局范围内禁用它们。要做到这一点：

全局禁用它作为工具。
在你的智能体配置中，启用 MCP 服务器作为工具。

{
  "$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 模式 Glob patterns

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

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

示例 Examples

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

Sentry

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

{
  "$schema": "https://opencode.ai/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 服务器以搜索文档。

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

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

{
  "$schema": "https://opencode.ai/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 中添加如下内容。

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

Grep by Vercel

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

{
  "$schema": "https://opencode.ai/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 中添加如下内容。

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