--- title: MCP服务器 description: 添加本地和远程MCP工具。 --- 您可以使用“模型上下文协议”或MCP将外部工具添加到OpenCode。OpenCode支持本地和远程服务器。 添加使用后，MCP工具将自动与内置工具一起供法学硕士。 --- #### 注意事項 当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快增加。因此，我们建议您选择使用哪些 MCP 服务器。 :::提示 MCP服务器会添加到您的上下文中，因此您需要小心启用哪些服务器。 ::: 某些MCP服务器（例如GitHub MCP服务器）往往会添加大量代币，并且很容易超出上下文限制。 --- ## 使能夠 您可以在`mcp`下的[开放代码配置](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" } } } } ``` `url` 是远程MCP服务器的URL，使用`headers`选项您可以创建标头列表。 --- #### 選項 |選項|類型 |必填 |描述 | | --------- | ------- | -------- | ----------------------------------------------------------------------------------- | | `type` |字符串|是| MCP 服务器连接类型，必须是`"remote"`。 | | `url` |字符串|是|远程MCP服务器的URL。 | `enabled` | 布尔 | |在启动时启用或禁用MCP 服务器。 | `headers` |对象| |随请求一起发送的标头。 | `oauth` |对象| | OAuth 身份验证。请参阅下面的配置[开放认证](#oauth) 部分。 | | `timeout` | 数量 | |从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 | --- ## 開放認證 OpenCode自动处理远程MCP服务器的OAuth身份验证。当服务器需要身份验证时，OpenCode将： 1. 检测 401 响应并启动 OAuth 流程 2. 如果服务器支持，请使用**动态客户端注册 (RFC 7591)** 3. 安全地存儲令牌以供將來的請求 --- ### 自動的 对于大多数支持 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 將在您第一次嘗試使用它時提示您進行身份驗證。如果沒有，您可以使用 `opencode mcp auth `[手動觸發流量](#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 ``` `mcp auth` 命令将打开您的浏览器进行授权。授权后，OpenCode 令牌安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。 --- #### 禁用 OAuth 如果要禁用服务器的自动OAuth（例如，对于使用API密钥的服务器），则`oauth`设置为`false`： ```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 选项 |選項|類型 |描述 | | -------------- | --------------- | -------------------------------------------------------------------------------- | | `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` 等） - `?` 恰好匹配一個字符 - 所有其他字符均按字面意思匹配 :::笔记 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. ```