512 lines
13 KiB
Plaintext
512 lines
13 KiB
Plaintext
---
|
||
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 <server-name>` 命令将打开您的浏览器进行授权。授权后，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.
|
||
```
|