---
title: MCP 伺服器
description: 添加本地和遠端 MCP 工具。
---

您可以使用「模型上下文協定」或 MCP 將外部工具添加到 opencode。 opencode 支援本地和遠端伺服器。

添加後，MCP 工具將自動與內建工具一起供 LLM 使用。

---

#### 注意事項

當您使用 MCP 伺服器時，它會添加到上下文中。如果您有很多工具，這會很快增加。因此，我們建議您謹慎選擇使用哪些 MCP 伺服器。

:::tip
MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些伺服器。
:::

某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會添加大量 tokens，並且很容易超出上下文限制。

---

## 啟用

您可以在 `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` 設定為 `"remote"` 添加遠端 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](#oauth) 部分。            |
| `timeout` | 數量   |      | 從 MCP 伺服器獲取工具的超時（以毫秒為單位）。預設為 5000（5 秒）。 |

---

## OAuth

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 <server-name>` [手動觸發流程](#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`        | Object \| false | OAuth 設定物件，或 `false` 以禁用 OAuth 自動檢測。  |
| `clientId`     | String          | OAuth 客戶端 ID。如果未提供，將嘗試動態客戶端註冊。 |
| `clientSecret` | String          | OAuth 客戶端密鑰（如果授權伺服器需要）。            |
| `scope`        | String          | 授權期間請求的 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 模式

glob 模式使用簡單的正規表示式 globbing 模式：

- `*` 匹配零個或多個任意字元（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
- `?` 恰好匹配一個字元
- 所有其他字元均按字面意思匹配

:::note
MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用伺服器的所有工具，只需使用：

```
"mymcpservername_*": false
```

:::

---

## 範例

以下是一些常見 MCP 伺服器的範例。如果您想記錄其他伺服器，您可以提交 PR。

---

### Sentry

添加 [Sentry 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
```

---

### Context7

添加 [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
```

或者，您可以將類似的內容添加到您的 [AGENTS.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
```

或者，您可以將類似的內容添加到您的 [AGENTS.md](/docs/rules/)。

```md title="AGENTS.md"
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
```
