---
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.
```
