AIチュートリアル

Open MCP GatewayでローカルMCPサービス向けのOpenAPIゲートウェイを構築する

Open MCP Gatewayのインストール、ローカルMCPサービスの設定、OpenAPI互換ルートの生成、Open WebUIとの統合、外部プラグインの管理、ログの監視、ゲートウェイのスタンドアロンネイティブ実行ファイルへのコンパイル方法を学びます。

2026年9月20日約14分で読了

Open MCP GatewayでローカルMCPサービス向けのOpenAPIゲートウェイを構築

Open MCP Gatewayとは？

Open MCP Gateway（略称OMG）は、ローカルにデプロイされたModel Context Protocolサービスを、OpenAPI 3.1.0に準拠したHTTP RESTルートとして公開する高性能ゲートウェイです。Bun 1.4とTypeScriptで構築され、Open WebUIエコシステム向けに設計されています。ただし、コミュニティプロジェクトであり、Open WebUIチームとは関係ありません。

このゲートウェイは、外部クライアントと1つ以上のMCPサービスの間に位置します。Open WebUIなどのクライアントはHTTPまたはHTTPS経由でゲートウェイと通信し、ゲートウェイは基盤となるMCPトランスポートを管理して、それらのツールをOpenAPI互換のインターフェースに変換します。

OMGは、ネイティブバイナリstdioサービス、NodeまたはBunのスクリプトベースstdioパイプライン、SSEまたはHTTPネットワークトランスポートをサポートします。これにより、異なる実行モデルや通信モデルを使用するMCPサービスに、一貫したHTTPインターフェースを提供できます。

主な機能

厳密なOpenAPI 3.1.0出力：ツールの入力スキーマはrequestBody.content['application/json'].schemaに配置されます。生成されるoperationIdは、tool_*_postのような名前を追加せず、元のMCPツール名を保持します。
複数のMCPトランスポート：ネイティブバイナリstdio、スクリプトstdio、SSE、HTTPサービスを1つのゲートウェイで管理できます。
ブルーグリーンセッションプール：サービスセッションはAsyncMutexの背後でホットスワップされるため、処理中のリクエストを中断せずに設定を更新できます。
ライフサイクル管理：ゲートウェイは、管理対象サービスのプロトコルラッピング、ライフサイクルの自己修復、ホットリロードを提供します。
クロスプラットフォーム対応のXDGレイアウト：設定、アプリケーションデータ、ランタイム状態、キャッシュファイルをソースリポジトリの外部に保持します。
スタンドアロンビルド：Bunを使って、ランタイム依存関係のないネイティブ実行可能ファイルにゲートウェイをコンパイルできます。
リバースプロキシ対応：ゲートウェイはX-Forwarded-*ヘッダーを読み取り、生成されるOpenAPIのservers.urlにクライアントから見える外部アドレスを反映します。

前提条件

ソースからプロジェクトを実行するには、Bun 1.4以降が必要です。また、登録するMCPサービスが少なくとも1つ必要です。サービスには、ローカルのネイティブ実行可能ファイル、Bunで起動するJavaScriptまたはTypeScriptパッケージ、SSEまたはHTTP経由で利用できるMCPサービスを使用できます。

ゲートウェイのインストールと実行

ソースから実行する

リポジトリをクローンまたはダウンロードしてディレクトリに移動し、依存関係をインストールして開発コマンドを起動します。

bun install
bun run dev

開発プロセスは、リポジトリ自体ではなく、プラットフォームのXDG設定ディレクトリからゲートウェイ設定を読み込みます。

スタンドアロン実行可能ファイルをビルドする

ネイティブ実行可能ファイルを作成するには、次を実行します。

bun run build

出力先は、Unix系システムではbuild/mcp-gateway、Windowsではbuild/mcp-gateway.exeです。デプロイ時、コンパイル済みバイナリに別途Bunランタイムは必要ありません。

XDGディレクトリレイアウトを理解する

Open MCP Gatewayは、用途ごとにファイルを分離します。これにより、生成データ、インストール済みプラグイン、ログ、キャッシュがソースツリーを汚染するのを防ぎます。

設定：XDG_CONFIG_HOMEにはメインのmcp-gateway/config.json5ファイルが含まれます。
データ：XDG_DATA_HOMEには外部MCPプラグインリポジトリと、その独自のpackage.jsonが含まれます。
状態：XDG_STATE_HOMEにはランタイム状態と永続ログが保存されます。
キャッシュ：XDG_CACHE_HOMEには仕様書類のキャッシュと一時的なランタイムデータが保存されます。

メイン設定ファイルのパスは次のとおりです。

$XDG_CONFIG_HOME/mcp-gateway/config.json5

このファイルはJSON5を使用するため、コメントと末尾のカンマを使用できます。

MCPサービスを設定する

必要に応じて設定ディレクトリを作成し、config.json5を追加します。次の例では、ネイティブMCP実行可能ファイルを1つと、パッケージベースのMCPサービスを1つ登録しています。

{
    mcpServers: {
        // ネイティブバイナリstdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // スクリプトstdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

mcpServers内の各キーは、MCPサービスを識別します。ネイティブバイナリの場合は、commandに実行可能ファイルのパスを設定します。パッケージベースのサービスの場合は、コマンドにBunを指定し、インストール済みスクリプトのパスをargsに渡します。サービス固有の環境変数はenvに追加できます。

ゲートウェイは、パス内の環境変数展開をサポートします。使用できる変数は${APP_DATA_DIR}、${XDG_DATA_HOME}、${HOME}、%USERPROFILE%です。展開を使用すると、すべての絶対パスをハードコードせずに、複数のコンピューターで再利用しやすい設定にできます。

サービス識別子は固定してください。たとえば、codebase_memoryという名前のサービスは、そのOpenAPIドキュメントを取得する際に使用される対応URLパスで公開されます。

外部MCPプラグインを管理する

業務固有のMCPパッケージは、ゲートウェイリポジトリにインストールしないでください。代わりに、ゲートウェイのXDGデータディレクトリにインストールして管理します。

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

インストール済みパッケージをアップグレードするには、次を実行します。

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

インストール後、スクリプトのstdio例に示されているように、${APP_DATA_DIR}を使用してconfig.json5からパッケージのエントリーポイントを参照します。これにより、ゲートウェイの依存関係をMCP拡張機能の依存関係から分離できます。

基本的な使い方

ゲートウェイの依存関係をインストールするか、ネイティブ実行ファイルをビルドします。
$XDG_CONFIG_HOME/mcp-gateway/config.json5を作成します。
mcpServersの下に1つ以上のサービスを追加します。
bun run devでゲートウェイを起動するか、コンパイル済みの実行ファイルを起動します。
設定したサービスのOpenAPIドキュメントを取得し、外部クライアントに登録します。

codebase_memoryという名前のサービスの場合、ドキュメントに記載されているOpenAPI URLのパターンは次のとおりです。

http://<gateway-host>:8444/codebase_memory/openapi.json

この例では、8444が外部からアクセス可能なポートです。設定例の9090のように、ゲートウェイの内部ポートではなくリバースプロキシのポートの場合もあります。

Open WebUIとの統合

CaddyやNginxなどのリバースプロキシを使用すると、ゲートウェイを任意の外部ホスト、ポート、プロトコルで公開できます。適切なX-Forwarded-*ヘッダーを送信するようにプロキシを設定してください。Open MCP GatewayはOpenAPIドキュメントの生成時にこれらのヘッダーを読み取り、servers.urlが内部のリスナーではなくパブリックアドレスを指すようにします。

リバースプロキシの背後でOpen MCP Gatewayを起動します。
Open WebUIの管理パネルを開きます。
Functions、Tools、またはOpenAPIのエリアに移動します。
設定した各MCPサービスのOpenAPIドキュメントURLを登録します。
```
http://<gateway-host>:8444/codebase_memory/openapi.json
```
Open WebUIが仕様を読み込めるようにします。これで、生成されたOpenAPI操作を通じて、MCPサービスのツールをネイティブツールとして利用できます。

操作IDは元のMCPツール名を保持するため、クライアントにはゲートウェイが生成した接尾辞や接頭辞のない、わかりやすいツール識別子が表示されます。

テストとログ監視

ゲートウェイまたはその設定を変更した後は、プロジェクトのテストコマンドを実行します。

bun run test

Windowsでは、リポジトリにPowerShellのテストスクリプトも用意されています。

.\ps1_scripts\test-gateway.ps1

エンドツーエンドのアサーションでは、ヘルスチェック、MCPハンドシェイク、プロキシのオリジン整合性を検証します。

Unix系システムでは、次のコマンドで永続的なゲートウェイログを追跡できます。

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

これは、プロセスの起動問題、実行ファイルパスの誤り、MCPハンドシェイクの失敗、リバースプロキシ設定の問題を診断する際に役立ちます。

高度なヒント

移植可能なパスを使用する

マシン固有の絶対パスよりも、${HOME}や${APP_DATA_DIR}などの補間パスを優先してください。Windowsでは、適切な場合に%USERPROFILE%を使用できます。これにより、複数のシステムで設定を共有しやすくなります。

プラグインをソースチェックアウトの外部に置く

外部MCPパッケージは$XDG_DATA_HOME/mcp-gatewayにインストールします。これによりソースツリーをクリーンに保ち、ゲートウェイとその業務拡張機能を独立してアップグレードできます。

内部アドレスと外部アドレスを分離する

ゲートウェイを127.0.0.1にバインドすると、内部リスナーをローカルに限定できます。その後、リバースプロキシで外部TLSエンドポイントを提供できます。生成されるOpenAPIドキュメントに正しいURLが示されるよう、転送ヘッダーがパブリックなスキーム、ホスト、ポートを正しく表していることを確認してください。

ホットアップデートを活用する

ブルーグリーンのセッションプールは、AsyncMutexで切り替えを保護しながらサービスセッションを入れ替えます。この設計により、実行中のリクエストを終了させずに設定を更新できます。ホットリロードとライフサイクルの自己修復機能により、手動でのプロセス管理もさらに減らせます。

デプロイ用にコンパイルする

ターゲットサーバーにBunやプロジェクトの依存関係をインストールしたくない場合は、bun run buildを使用します。生成された実行ファイルを、必要なXDG設定および個別に管理するMCPバイナリやパッケージとともにデプロイします。

まとめ

Open MCP Gatewayは、ローカルMCPサービスから厳密なOpenAPI 3.1.0ルートへの統合ブリッジを提供します。マルチトランスポート対応、移植可能なXDGベースの設定、外部プラグイン管理、リバースプロキシ対応、スタンドアロンビルドを組み合わせることで、ローカルMCPツールをOpen WebUIやその他のOpenAPI対応クライアントから利用できる実用的な方法を提供します。