跳到主要內容
啟用

MCP 伺服器

您可以透過 Model Context Protocol（MCP）為 OpenCode 新增外部工具。OpenCode 同時支援本地和遠端伺服器。

新增後，MCP 工具會自動與內建工具一起提供給 LLM 使用。

注意事項

使用 MCP 伺服器時，它會佔用上下文空間。如果您啟用了大量工具，上下文消耗會迅速增加。因此，我們建議謹慎選擇要使用的 MCP 伺服器。

某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會消耗大量 Token，很容易超出上下文限制。

您可以在 OpenCode 設定的 mcp 欄位下定義 MCP 伺服器。為每個 MCP 指定一個唯一的名稱，在提示詞中可以透過該名稱來參照對應的 MCP。

opencode.jsonc
{
  "$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：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

本地設定值會覆寫遠端預設值。詳情請參閱設定優先順序。

透過在 MCP 物件中將 type 設定為 "local" 來新增本地 MCP 伺服器。

opencode.jsonc
{
  "$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",
      },
    },
  },
}

command 用於指定本地 MCP 伺服器的啟動指令。您還可以傳入一組環境變數。

例如，以下是新增測試用的 @modelcontextprotocol/server-everything MCP 伺服器的方法。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

要使用它，可以在提示詞中新增 use the mcp_everything tool。

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 伺服器。

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 伺服器的位址，透過 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. 安全地儲存 Token 以供後續請求使用

對於大多數支援 OAuth 的 MCP 伺服器，無需特殊設定。只需設定遠端伺服器即可：

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> 手動觸發認證流程。

如果您已經從 MCP 伺服器提供商處取得了用戶端憑證，可以直接設定：

opencode.json
{
  "$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 伺服器進行身分驗證：

終端機
opencode mcp auth my-oauth-server

列出所有 MCP 伺服器及其認證狀態：

終端機
opencode mcp list

刪除已儲存的憑證：

終端機
opencode mcp logout my-oauth-server

mcp auth 指令會開啟瀏覽器進行授權。授權完成後，OpenCode 會將 Token 安全地儲存在 ~/.local/share/opencode/mcp-auth.json 中。

停用 OAuth

如果您想為某個伺服器停用自動 OAuth（例如，該伺服器使用 API 金鑰而非 OAuth），可以將 oauth 設定為 false：

opencode.json
{
  "$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物件 | falseOAuth 設定物件，或設為 false 以停用 OAuth 自動偵測。
clientId字串OAuth 用戶端 ID。如果未提供，將嘗試動態用戶端註冊。
clientSecret字串OAuth 用戶端密鑰（如果授權伺服器要求提供）。
scope字串授權時請求的 OAuth 作用域。

偵錯

如果遠端 MCP 伺服器身分驗證失敗，您可以透過以下方式診斷問題：

終端機
# 查看所有支援 OAuth 的伺服器的認證狀態
opencode mcp auth list

# 偵錯特定伺服器的連線和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 指令會顯示當前認證狀態、測試 HTTP 連線，並嘗試執行 OAuth 發現流程。

您的 MCP 在 OpenCode 中作為工具使用，與內建工具並列。因此，您可以像管理其他工具一樣，透過 OpenCode 設定來管理它們。

您可以全域啟用或停用 MCP 工具。

opencode.json
{
  "$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。

opencode.json
{
  "$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. 在代理設定中，將 MCP 伺服器作為工具啟用。
opencode.json
{
  "$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 模式使用簡單的正規表示式萬用字元規則：

  • * 比對零個或多個任意字元（例如，"my-mcp*" 比對 my-mcp_search、my-mcp_list 等）
  • ? 比對恰好一個字元
  • 其他字元按字面值比對

以下是一些常見 MCP 伺服器的設定範例。如果您想記錄其他伺服器的用法，歡迎提交 PR。

新增 Sentry MCP 伺服器 以與您的 Sentry 專案和問題進行互動。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

新增設定後，使用 Sentry 進行身分驗證：

終端機
opencode mcp auth sentry

這會開啟瀏覽器視窗完成 OAuth 流程，將 OpenCode 連結到您的 Sentry 帳號。

認證完成後，您可以在提示詞中使用 Sentry 工具來查詢問題、專案和錯誤資料。

Show me the latest unresolved issues in my project. use sentry

新增 Context7 MCP 伺服器 以搜尋文件。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

如果您註冊了免費帳號，可以使用 API 金鑰來取得更高的速率限制。

opencode.json
{
  "$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 伺服器。

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

您也可以在 AGENTS.md 中新增類似的規則。

AGENTS.md
When you need to search docs, use `context7` tools.

新增 Grep by Vercel MCP 伺服器以搜尋 GitHub 上的程式碼片段。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

由於我們將 MCP 伺服器命名為 gh_grep，您可以在提示詞中新增 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 中新增類似的規則。

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