OpenCodeの設定 - MCPサーバ

提供: MochiuWiki : SUSE, EC, PCB

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

MCP (Model Context Protocol) は、LLMと外部ツールの統合を標準化したオープンプロトコルである。
OpenCodeはMCPクライアントとして機能し、MCPサーバを経由して外部システムへのアクセスを実現する。

MCPを使用することにより、以下に示すメリットが得られる。

  • 統一されたインターフェース
    複数のツールとサービスを標準化されたプロトコルで接続できる。
  • 自然言語による操作
    データベース、コード検索、外部API、ファイルシステム等を自然言語で操作できる。
  • 複数サーバの同時接続
    OpenCodeは複数のMCPサーバを同時に接続して使用できる。
  • 幅広いエコシステム
    コミュニティによって開発された多数のMCPサーバが利用可能である。



MCPの基本構造

MCPは、MCPクライアント (OpenCode) と MCPサーバ (外部システムへの接続を提供) の間で通信を行うプロトコルである。

MCPサーバ と MCPクライアント

MCPクライアントとMCPサーバの役割
種別 説明
MCPクライアント OpenCodeがクライアントとして機能し、MCPサーバに接続する。
ユーザの自然言語リクエストをMCPサーバへのツール呼び出しに変換する。
MCPサーバ 外部システム (GitHub、データベース、各種API等) への接続を提供する。
ツール、リソース、プロンプトの3つの主要機能を提供する。


サーバタイプ

MCPサーバは、下表にある2種類のトランスポート方式で接続される。

MCPサーバのサーバタイプ
タイプ トランスポート方式 説明 主な用途
local stdio (標準入出力) ローカルプロセスとして起動し、標準入出力で通信する。 ファイルシステム操作、ローカルツール
remote HTTP / SSE (Server-Sent Events) URLで指定したリモートサーバと通信する。 クラウドAPI、外部サービス



ディレクトリ構造

MCPサーバの設定は opencode.json で管理する。
設定ファイルはプロジェクト固有またはグローバルの2か所に配置できる。

MCPサーバ設定ファイルのパス
スコープ ファイルパス 説明
プロジェクト固有 .opencode/opencode.json 現在のプロジェクトのみで有効
グローバル ~/.config/opencode/opencode.json 全プロジェクトで有効


プロジェクト固有の設定がグローバル設定より優先される。


MCPサーバの設定方法

ローカルMCPサーバの設定

ローカルMCPサーバは、type: "local" を指定してコマンドとして設定する。
command フィールドにはサーバを起動するコマンドを配列形式で指定する。

  • ローカルMCPサーバの設定例 
     {
    "mcp": {
       "filesystem": {
          "type": "local",
          "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"],
          "enabled": true
       },
       "sequential-thinking": {
          "type": "local",
          "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
          "enabled": true
       }
    }
 }

  • 環境変数が必要なサーバは、environment フィールドで設定する。 
     {
    "mcp": {
       "my-local-mcp": {
          "type": "local",
          "command": ["npx", "-y", "mcp-server-example"],
          "environment": {
             "API_KEY": "<APIキー>"
          },
          "enabled": true
       }
    }
 }


リモートMCPサーバの設定

リモートMCPサーバは、type: "remote" を指定してURLで設定する。

  • APIキーによる認証が必要なサーバの設定例 
     {
    "mcp": {
       "my-remote-mcp": {
          "type": "remote",
          "url": "https://my-mcp-server.com",
          "headers": {
             "Authorization": "Bearer {env:API_TOKEN}"
          },
          "enabled": true
       }
    }
 }

  • OAuth認証を使用するサーバの設定例
    oauth: true を指定することで自動的にOAuth認証フローが実行される。
     {
    "mcp": {
       "oauth-mcp": {
          "type": "remote",
          "url": "https://oauth-mcp-server.com",
          "enabled": true,
          "oauth": true
       }
    }
 }


{env:変数名} の記法を使用することにより、設定ファイルに直接APIキーを記述せず、環境変数から値を参照できる。


MCPサーバの管理コマンド

OpenCodeはMCPサーバの管理のためのCLIコマンドを提供する。

MCPサーバ管理のCLIコマンド
コマンド 説明
opencode mcp list 設定済みのMCPサーバを一覧表示する。
opencode mcp add 対話的にMCPサーバを追加する。
opencode mcp remove <server-name> 指定したMCPサーバを削除する。
opencode mcp auth <server-name> 指定したMCPサーバの認証を手動で実行する。
opencode mcp debug <server-name> 指定したMCPサーバの接続をデバッグする。


使用例を以下に示す。

# MCPサーバの一覧を表示
opencode mcp list

# MCPサーバを追加 (対話的)
opencode mcp add

# MCPサーバを削除
opencode mcp remove my-server

# 認証を手動実行
opencode mcp auth my-oauth-server

# 接続をデバッグ
opencode mcp debug my-server



認証管理

OAuth認証

リモートMCPサーバのOAuth認証は、以下のフローで自動的に処理される。

  1. サーバへのリクエスト時に401レスポンスを検出する。
  2. OAuth 2.0認証フローを開始する。
  3. Dynamic Client Registration (動的クライアント登録) を実行する。
  4. ブラウザでの認証が完了すると、アクセストークンを取得する。
  5. トークンをローカルに保存して以降のリクエストで使用する。


取得したトークンは、以下に示すパスに保存される。

  • ~/.local/share/opencode/mcp-auth.json


このファイルには認証トークンが含まれるため、適切なファイルパーミッションを設定することを推奨する。

chmod 600 ~/.local/share/opencode/mcp-auth.json


認証コマンド

OAuth認証を手動で実行する場合は、以下のコマンドを使用する。

opencode mcp auth <サーバ名>


APIキー認証を使用する場合は、oauth: false を指定して headers にAPIキーを設定する。

 {
    "mcp": {
       "api-key-mcp": {
          "type": "remote",
          "url": "https://api-mcp-server.com",
          "headers": {
             "Authorization": "Bearer {env:<APIキー>}"
          },
          "oauth": false,
          "enabled": true
       }
    }
 }



MCPツールの権限設定

MCPサーバが提供するツールの実行権限を設定できる。

MCPツールの権限設定値
設定値 説明
ask ツールの実行前にユーザに確認を求める。(デフォルト)
allow 確認なしにツールの実行を許可する。
deny ツールの実行を拒否する。


権限設定の例を以下に示す。

 {
    "mcp": {
       "filesystem": {
          "type": "local",
          "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
          "enabled": true,
          "permissions": "allow"
       },
       "dangerous-tool": {
          "type": "remote",
          "url": "https://example.com",
          "enabled": true,
          "permissions": "ask"
       }
    }
 }



人気のMCPサーバ一覧

OpenCodeで利用できる人気のMCPサーバを以下に示す。

人気のMCPサーバ一覧
サーバ名 カテゴリ 説明 タイプ
Sentry MCP 監視・デバッグ エラー追跡と監視を実行する remote
Context7 MCP ドキュメント 最新の技術ドキュメントを取得する local / remote
GitHub MCP 開発ツール GitHubのリポジトリ、PR、Issueを管理する remote
Appwrite MCP バックエンド Appwriteのバックエンドサービスを操作する remote
Netdata MCP 監視 システムのリアルタイム監視データを取得する remote
Sanity MCP CMS SanityのコンテンツマネジメントシステムをAIで操作する remote



設定例

複数のMCPサーバを組み合わせた設定例を以下に示す。

 {
    "mcp": {
       "context7": {
          "type": "local",
          "command": ["npx", "-y", "@upstash/context7-mcp"],
          "environment": {
             "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
          },
          "enabled": true
       },
       "github": {
          "type": "remote",
          "url": "https://api.githubcopilot.com/mcp/",
          "headers": {
             "Authorization": "Bearer {env:GITHUB_TOKEN}"
          },
          "enabled": true
       },
       "sentry": {
          "type": "remote",
          "url": "https://mcp.sentry.dev/mcp",
          "enabled": true,
          "oauth": true
       },
       "filesystem": {
          "type": "local",
          "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
          "enabled": true,
          "permissions": "ask"
       }
    }
 }



セキュリティ上の注意事項

MCPサーバを使用する場合は、以下に示すセキュリティ上の注意事項を遵守することを推奨する。

コンテキストサイズへの影響

MCPツールを追加するとコンテキストウィンドウのサイズが増加する。

  • 不要なMCPサーバは enabled: false に設定して無効化する。
  • 必要なサーバのみを有効にしてコンテキストサイズを最適化する。
  • ツールの数が多い場合は応答速度に影響することがある。


認証情報の管理

APIキーや認証情報の管理には以下に示す事柄に注意する。

  • APIキーは {env:変数名} の記法を使用して環境変数から参照する。
    設定ファイルにAPIキーを直接記述しない。
  • opencode.json を .gitignoreファイル に追加してバージョン管理から除外する。
    特にAPIキーが含まれる場合は必ず除外する。
  • ~/.local/share/opencode/mcp-auth.json のパーミッションを適切に設定する。
    chmod 600 ~/.local/share/opencode/mcp-auth.json を実行することを推奨する。


信頼できるソースの使用

MCPサーバは、信頼できるソースからのみ追加することを推奨する。

  • 公式が提供するMCPサーバを優先する。
  • コミュニティで実績のあるサーバを使用する。
  • 出所不明のサーバは追加しない。
  • SSE接続に問題が発生した場合は、HTTPストリーミングへの切り替えを検討する。



トラブルシューティング

MCPサーバが認識されない

設定ファイルが正しい場所に配置されているか確認する。

  • 設定ファイルのパスを確認する
    プロジェクト固有
    .opencode/opencode.json

    グローバル
    ~/.config/opencode/opencode.json

  • JSON構文を確認する。
    JSON形式が正しいか、括弧の対応が取れているかを確認する。

  • OpenCodeを再起動する。
    設定変更後はOpenCodeを再起動することで反映される。


MCPサーバへの接続に失敗する

接続に失敗する場合は、以下に示す事柄を確認する。

  • URLが正しいか確認する。
    リモートサーバのURLに誤りがないか確認する。

  • 環境変数が設定されているか確認する。
    {env:変数名} で参照している環境変数が設定されているか確認する。

  • ネットワーク接続を確認する
    サーバへのネットワーク疎通があるか確認する。

  • デバッグコマンドを実行する。
    opencode mcp debug <サーバ名> で詳細なエラー情報を確認する。


ローカルサーバが起動しない

ローカルMCPサーバが起動しない場合は、以下の点を確認する。

  • コマンドが存在するか確認する。
    command フィールドに指定したコマンドがインストールされているか確認する。

  • npxが使用可能か確認する。
    npx コマンドが利用可能な環境か確認する。

  • 権限を確認する。
    コマンドの実行権限があるか確認する。


SSE接続に問題がある

SSE (Server-Sent Events) 接続に問題が発生した場合は、HTTPストリーミングへの切り替えを検討する。
SSEはOpenCodeでの使用が推奨されていない。

サーバがHTTPトランスポートをサポートしている場合は、type: "remote" でURLを指定するHTTP形式に切り替える。


「http://mochiuwiki.e2.valueserver.jp/index.php?title=OpenCodeの設定_-_MCPサーバ&oldid=14368」から取得