OpenCode MCP サーバー設定

MCP（Model Context Protocol、モデルコンテキストプロトコル）は、OpenCode に外部ツールやデータソースを接続できるようにするオープンプロトコルです。MCP サーバーを追加すると、そのサーバーが提供するツールは OpenCode の組み込みツールと自動的に並び、LLM は会話中にそれらを直接呼び出すことができます。

OpenCode は次の 2 種類の MCP サーバーをサポートしています：

  • ローカル（local）：お使いのマシン上でコマンドラインから起動する MCP プロセスで、ローカルツールやスクリプトに適しています
  • リモート（remote）：HTTPS 経由で接続するリモートの MCP サービスで、クラウドサービスやサードパーティプラットフォームに適しています

コンテキスト消費に関する注意：各 MCP サーバーは、会話のコンテキスト領域を消費します。有効化するツールが多いほど、毎回の会話で消費する Token が増え、モデルのコンテキスト上限に達しやすくなります。現在のタスクで実際に必要な MCP サーバーのみを有効にし、使い終わったらすぐに無効化することをお勧めします。一部のサーバー（GitHub MCP など）はツール数が非常に多く、Token の消費が特に顕著です。使用時は十分に注意してください。

基本設定構造

すべての MCP サーバー設定はopencode.jsonのmcpフィールドに記述します。各サーバーには一意の名前をキー名として使用します。この名前は、プロンプト内でどの MCP を呼び出すかを指定する際にも使用できます：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local 或 remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

将 enabledに設定すると、falseサーバーを一時的に無効化でき、設定ファイルから削除する必要もなく、必要に応じてオン/オフを切り替えられます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // 一時的に無効化。設定は保持され、次回必要になったら true に戻すだけです
    }
  }
}

ローカル MCP サーバー

ローカル MCP サーバーは、お使いのマシン上でコマンドプロセスを実行してツールを提供します。typeを"local"に設定し、commandで起動コマンドを指定します：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",                                   // 接続タイプ：ローカル
      "command": ["npx", "-y", "my-mcp-command"],        // 起動コマンド配列：
                                                         // 最初の要素は実行可能ファイル、
                                                         // 後続の要素は引数です
                                                         // 次のように書くこともできます：["bun", "x", "my-mcp-command"]
      "enabled": true,
      "environment": {                                   // 実行時に注入する環境変数（オプション）
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

ローカルサーバー設定項目

設定項目 型 必須 説明
type 文字列 である 接続タイプ。ローカルサーバーの場合は必須です"local"
command 配列 である MCP サーバーを起動するコマンドと引数。配列形式。例：["npx", "-y", "my-mcp"]
environment オブジェクト 否 サーバー実行時に注入する環境変数。キーと値のペア形式
enabled ブール値 否 起動時にこのサーバーを有効にするかどうか。デフォルトはtrue
timeout 数値 否 MCP サーバーからツールリストを取得する際のタイムアウト時間（ミリ秒）。デフォルトは5000（5 秒）

例：テスト用 MCP サーバーを追加する

以下は、公式のテスト用 MCP サーバー@modelcontextprotocol/server-everythingを追加する例です。MCP 機能が正常に動作するかどうかの検証に使用できます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y はインストールを自動確認するため、手動での npm install は不要です
    }
  }
}

設定が完了したら、プロンプトにサーバー名を追加することで、LLM にその MCP のツールを呼び出させることができます：

use the mcp_everything tool to add the number 3 and 4

リモート MCP サーバー

リモート MCP サーバーは、HTTPS 経由でクラウドサービスに接続します。typeを"remote"に設定し、urlでサーバーアドレスを指定します：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // 接続タイプ：リモート
      "url": "https://my-mcp-server.com",             // リモートサーバーアドレス（必須）
      "enabled": true,
      "headers": {                                    // リクエストとともに送信する HTTP ヘッダー（オプション）
        "Authorization": "Bearer MY_API_KEY"          // 通常は API キー認証に使用します
      }
    }
  }
}

リモートサーバー設定項目

設定項目 型 必須 説明
type 文字列 である 接続タイプ。リモートサーバーの場合は必須です"remote"
url 文字列 である リモート MCP サーバーの完全な HTTPS アドレス
enabled ブール値 否 起動時にこのサーバーを有効にするかどうか。デフォルトはtrue
headers オブジェクト 否 各リクエストに添付して送信する HTTP ヘッダー。通常は API キー認証に使用します
oauth オブジェクト /false 否 OAuth 認証設定。またはfalseに設定すると、自動 OAuth 検出が無効化されます
timeout 数値 否 MCP サーバーからツールリストを取得する際のタイムアウト時間（ミリ秒）。デフォルトは5000（5 秒）

環境変数を参照する

設定ファイル内では、API キーなどの機密情報を平文で直接記述すべきではありません。OpenCode は{env:变量名}構文を使用して、実行時にシステム環境変数を読み取ることができます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"    // 実行時に環境変数 MY_API_KEY の値を自動的に読み取ります
                                                      // 事前にシステムでこの環境変数を設定しておく必要があります：
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

OAuth 認証

OpenCode にはリモート MCP サーバー向けの OAuth 認証サポートが組み込まれており、フロー全体がほぼ全自動で、Token を手動で処理する必要はありません。

自動認証フロー

サーバーが OAuth 認証を必要とする場合、OpenCode は以下の手順を自動的に実行します：

  1. サーバーが 401（Unauthorized）応答を返したことを検出します
  2. OAuth 認可フローを自動的に開始し、ブラウザを開いてログインを案内します
  3. サーバーがサポートしている場合、動的クライアント登録（RFC 7591）を使用してアプリを自動登録します
  4. 取得した Token を安全に保存します~/.local/share/opencode/mcp-auth.json 中
  5. 以降のリクエストには Token が自動的に付与されるため、再ログインは不要です

1、自動OAuth（追加設定不要）

ほとんどの OAuth 対応 MCP サーバーでは、urlを設定するだけで、OpenCode が初回使用時に自動的に認証を案内します：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // 追加設定は一切不要で、OpenCode が OAuth フローを自動処理します
    }
  }
}

認証フローを手動でトリガーすることもできます（例：Token の有効期限切れ後に再ログインする場合）：

opencode mcp auth my-oauth-server

2、事前登録済みクライアント認証情報

サービスプロバイダーから固定のクライアント ID とシークレットを既に取得している場合は、設定内で直接指定して、動的登録の手順をスキップできます：

例

{
  "$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"             // 要求する権限スコープ。具体的な値はサービスプロバイダーが定めます
      }
    }
  }
}

3、OAuth を無効にする（API キー認証を使用）

サーバーが OAuth 認証ではなく API キーを使用する場合は、oauthをfalseに設定して自動 OAuth 検出を無効化し、headersでキーを渡します：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // OAuth の自動検出を無効化
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // API キーで直接認証する
      }
    }
  }
}

OAuth 設定項目

設定項目 型 説明
oauth オブジェクト /false OAuth 設定オブジェクト。設定するとfalseOAuth 自動検出を完全に無効化できます
clientId 文字列 OAuth クライアント ID。未提供の場合、OpenCode は動的クライアント登録を試みます
clientSecret 文字列 OAuth クライアントシークレット（認可サーバーが要求する場合）
scope 文字列 認可時に要求する権限スコープ。複数の権限はスペースで区切ります。具体的な値はサービスプロバイダーが規定します

認証管理コマンド

OpenCode は MCP の認証状態を管理するためのコマンドラインツール群を提供しています：

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

リモートのデフォルト設定を上書きする

組織は.well-known/opencodeエンドポイントを通じてメンバーにプリセットの MCP サーバー設定を提供できます。これらのサーバーはデフォルトで無効になっている場合があります。特定のサーバーを有効にする必要がある場合は、ローカル設定に同じ名前のエントリを追加して設定しますenabled: trueだけで有効になります。ローカル設定はリモートのデフォルト値を上書きします：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // 組織のリモート設定のサーバー名と一致させます
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // ローカルで true に設定し、リモートのデフォルトの無効状態を上書きします
    }
  }
}

ツール管理

MCP サーバーが登録されると、そのツールは服务器名称_工具名称の形式で OpenCode のツールリストに表示され、toolsフィールドで一括管理できます。

1、指定した MCP のツールをグローバルに無効化する

例

{
  "$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    // my-mcp-foo サーバーのすべてのツールを無効化（サーバーは起動しますが、ツールは使用できません）
  }
}

2、Glob パターンによる一括無効化

Glob ワイルドカードを使用すると、複数の MCP サーバーのツールを一度にマッチングして無効化できます：

例

{
  "$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 で始まるすべてのサーバーのツールを無効化
  }
}

3、エージェントごとに特定の MCP ツールを有効化する

多数の MCP サーバーを設定しても、各エージェントが必要とするのはその一部だけの場合、まずすべての MCP ツールをグローバルに無効化し、その後特定のエージェントの設定で必要に応じて有効にできます。これにより、各エージェントがアクセスできるツールを正確に制御でき、コンテキストの無駄遣いを防げます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true         // サーバー自体は起動状態を維持します（そうしないとエージェントも使用できません）
    }
  },
  "tools": {
    "my-mcp*": false          // ステップ 1：この MCP のすべてのツールをグローバルに無効化。デフォルトの会話では使用不可
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true       // ステップ 2：my-agent エージェント内でのみ有効化。他のエージェントには影響なし
      }
    }
  }
}

Glob パターンのルール

ワイルドカード 意味 例
* ゼロ個以上の任意の文字にマッチ my-mcp*にマッチmy-mcp_search、my-mcp_list 等
? 任意の 1 文字に正確にマッチ my-mcp?にマッチmy-mcpA、しかしマッチしないmy-mcpAB
他の文字 リテラル値として正確にマッチ my-mcp-foo名前が完全に一致するサーバーのみにマッチ

MCP サーバーのツールは登録時にサーバー名がプレフィックスとして付加されます。例えば、サーバーmyserverのツールはmyserver_toolnameとして登録されます。したがって、特定のサーバーのすべてのツールを無効化するには、"myserver_*": falseを使用すると正確にマッチできます。

設定例

Sentry

Sentry MCP サーバーを追加すると、会話内で Sentry プロジェクトのエラー、問題、イベントデータを直接照会できます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // 空のオブジェクトは OAuth 自動認証を有効にすることを示します。OpenCode が OAuth フロー全体を自動処理します
    }
  }
}

設定を追加したら、以下のコマンドを実行してアカウント認証を完了します（ブラウザが開き OAuth ログインが実行されます）：

opencode mcp auth sentry

認証完了後、プロンプトにuse sentryを追加すると Sentry ツールを呼び出せます：

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

Context7

Context7 MCP サーバーを追加すると、会話内で各種技術ドキュメントを検索でき、LLM が最新かつ正確な API リファレンスを取得するのに役立ちます：

例

// ベーシック版（レート制限の最適化なし）
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

例

// 無料アカウントを登録すると、API キーを使用してより高いレート制限を得られます
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // 環境変数から API キーを読み取ります
                                                        // 事前に設定が必要：export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

プロンプトにuse context7を追加するとドキュメント検索機能を呼び出せます：

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

プロジェクトのAGENTS.mdにグローバルルールを追加することもできます。LLM がドキュメントを確認する必要がある場合に自動的に Context7 を使用するため、毎回手動で指定する必要はありません：

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

Grep by Vercel

Grep by Vercel MCP サーバーを追加すると、会話内で GitHub 上の実際のコードスニペットを直接検索でき、LLM が正しい API の使用方法や実装の参考を見つけるのに役立ちます：

例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // サーバー名は gh_grep にします。プロンプトではこの名前で参照します
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

プロンプトにuse the gh_grep toolを追加すると GitHub 上のコード例を検索できます：

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

同様にAGENTS.mdにグローバルルールを設定すると、LLM が使用方法が不明な場合に自動的にコード例を検索できます：

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
その他の拡張機能