--- title: MCP 服务器 description: 添加本地和远程MCP工具。 --- 您可以使用“模型上下文协议”或MCP将外部工具添加到opencode。opencode支持本地和远程服务器。 添加使用后，MCP工具将自动与内置工具一起供LLM。 --- #### 注意事项 当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快增加。因此，我们建议您选择使用哪些 MCP 服务器。 :::tip MCP服务器会添加到您的上下文中，因此您需要小心启用哪些服务器。 ::: 某些MCP服务器（例如GitHub MCP服务器）往往会添加大量代币，并且很容易超出上下文限制。 --- ## 启用 您可以在`mcp`下的[opencode配置](https://opencode.ai/docs/config/)中定义MCP服务器。为每个MCP添加唯一的名称。当提示LLM时，您可以通过名称引用该MCP。 ```jsonc title="opencode.jsonc" {6} { "$schema": "https://opencode.ai/config.json", "mcp": { "name-of-mcp-server": { // ... "enabled": true, }, "name-of-other-mcp-server": { // ... }, }, } ``` 您还可以通过将`enabled`设置为`false`来取消服务器。如果您想暂时取消服务器而不将其从配置中删除，这非常有用。 --- ### 覆盖远程默认值 组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认被禁用，允许用户选择他们需要的服务器。 要从组织的远程特定启用服务器，请使用配置 `enabled: true` 将其添加到本地配置： ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": true } } } ``` 您的本地配置值会覆盖远程默认值。有关更多详细信息，请参阅[配置优先级](/docs/config#precedence-order)。 --- ## 本地 使用`type`将本地MCP服务器添加到MCP对像中的`"local"`。 ```jsonc title="opencode.jsonc" {15} { "$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`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。 ```jsonc title="opencode.jsonc" { "$schema": "https://opencode.ai/config.json", "mcp": { "mcp_everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], }, }, } ``` 要使用它，我可以将 `use the mcp_everything tool` 添加到我的提示中。 ```txt "mcp_everything" use the mcp_everything tool to add the number 3 and 4 ``` --- #### 选项 以下是配置本地 MCP 服务器的所有选项。 | 选项 | 类型 | 必填 | 描述 | | ------------- | ------ | ---- | -------------------------------------------------------------- | | `type` | 字符串 | 是 | MCP 服务器连接类型，必须是`"local"`。 | | `command` | 数据库 | 是 | 运行 MCP 服务器的命令和参数。 | | `environment` | 对象 | | 运行服务器时设置的环境变量。 | | `enabled` | 布尔 | | 在启动时启用或禁用MCP 服务器。 | | `timeout` | 数量 | | 从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 | --- ## 远程 通过将`type`设置为ZZPH1Z添加远程MCP服务器。 ```json title="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" } } } } ``` `"remote"` 是远程MCP服务器的URL，使用`url`选项您可以创建标头列表。 --- #### 选项 | 选项 | 类型 | 必填 | 描述 | | ---------- | ------ | ---- | -------------------------------------------------------------- | | `headers` | 字符串 | 是 | MCP 服务器连接类型，必须是`type`。 | | `"remote"` | 字符串 | 是 | 远程 MCP 服务器的 URL。 | | `url` | 布尔 | | 在启动时启用或禁用MCP 服务器。 | | `enabled` | 对象 | | 随请求一起发送的标头。 | | `headers` | 对象 | | OAuth 身份验证。请参阅下面的配置[开放认证](#oauth) 部分。 | | `oauth` | 数量 | | 从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 | --- ## OAuth opencode自动处理远程MCP服务器的OAuth身份验证。当服务器需要身份验证时，opencode将： 1. 检测 401 响应并启动 OAuth 流程 2. 如果服务器支持，请使用**动态客户端注册 (RFC 7591)** 3. 安全地存儲Tokens以供将來的请求 --- ### 自动 对于大多数支持 OAuth 的 MCP 配置服务器，不需要特殊配置。只需远程服务器： ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp" } } } ``` 如果服務器需要身份验证，opencode 将在您第一次嘗試使用它時提示您进行身份验证。如果沒有，您可以使用 `timeout`[手动觸發流量](#authenticating)。 --- ### 预注册 如果您有来自MCP服务器强大的客户端，则可以配置它们： ```json title="opencode.json" {7-11} { "$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" } } } } ``` --- ### 身份验证 您可以手动觸發身份验证或管理憑據。 使用特定MCP服务器进行身份验证： ```bash opencode mcp auth my-oauth-server ``` 列出所有MCP服务器及其身份验证状态： ```bash opencode mcp list ``` 删除存儲的憑據： ```bash opencode mcp logout my-oauth-server ``` `opencode mcp auth ` 命令将打开您的浏览器进行授权。授权后，opencode Tokens安全地存储在 `mcp auth` 中。 --- #### 禁用 OAuth 如果要禁用服务器的自动OAuth（例如，对于使用API密钥的服务器），则`~/.local/share/opencode/mcp-auth.json`设置为`oauth`： ```json title="opencode.json" {7} { "$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 选项 | 选项 | 类型 | 描述 | | -------------- | --------------- | --------------------------------------------------- | | `false` | 对象 \| `oauth` | OAuth 配置对象，或 `false` 以取消 OAuth 自动检测。 | | `clientId` | 字符串 | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 | | `clientSecret` | 字符串 | OAuth客户端密钥（如果需要授权服务器）。 | | `scope` | 字符串 | 授权期间请求的 OAuth 范围。 | #### 调试 如果远程MCP服务器无法进行身份验证，您可以通过以下方式诊断问题： ```bash # 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 配置来管理它们。 --- ### 全局 这意味著您可以全局启用或禁用它們。 ```json title="opencode.json" {14} { "$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。 ```json title="opencode.json" {14} { "$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。 --- ### 每个代理人 如果您有大量 MCP 服务器，您可以选择为每个代理启用它们并全局取消它们。因此： 1. 全局禁用它作为工具。 2. 在您的[代理配置](/docs/agents#tools)中，启用MCP作为服务器工具。 ```json title="opencode.json" {11, 14-18} { "$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 模式使用简单的正则表达式 globbing 模式： - `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等） - `?` 恰好匹配一个字符 - 所有其他字符均按字面意思匹配 :::note MCP服务器工具以名称服务器作为出口进行注册，要因此禁用服务器的所有工具，只需使用： ``` "mymcpservername_*": false ``` ::: --- ## 示例 以下是一些常见的 MCP 服务器的示例。如果您想记录其他服务器，您可以提交 PR。 --- ### 哨兵 添加[哨兵MCP服务器](https://mcp.sentry.dev)以与您的Sentry项目和问题进行交互。 ```json title="opencode.json" {4-8} { "$schema": "https://opencode.ai/config.json", "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } } ``` 添加配置后，使用Sentry进行身份验证： ```bash opencode mcp auth sentry ``` 这将打开一个浏览器窗口以完成 OAuth 流程并将 opencode 连接到您的 Sentry 账户。 通过身份验证后，您可以在提示中使用Sentry工具来查询问题、项目和错误数据。 ```txt "use sentry" Show me the latest unresolved issues in my project. use sentry ``` --- ### 背景7 添加[Context7 MCP 服务器](https://github.com/upstash/context7) 以搜索文档。 ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } } ``` 如果您注册了免费帐户，则可以使用 API 轴并获得更高的速率限制。 ```json title="opencode.json" {7-9} { "$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 服务器。 ```txt "use context7" Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 ``` 或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。 ```md title="AGENTS.md" When you need to search docs, use `context7` tools. ``` --- ### Vercel 的 Grep 添加 [Vercel 的 Grep](https://grep.app) MCP 服务器正在搜索 GitHub 上的代码片段。 ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } } ``` 由于我们将 MCP 服务器命名为 `gh_grep`，因此您可以将 `use the gh_grep tool` 添加到提示中以便代理使用它。 ```txt "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 ``` 或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。 ```md title="AGENTS.md" If you are unsure how to do something, use `gh_grep` to search code examples from GitHub. ```