mcpField
R
run-mcp-gateway

run-mcp-gateway

github.com/ngrokクラウド・DevOps18143 回インストール4 日前に更新
リポジトリ

run-mcp-gateway について

run-mcp-gatewayは、開発中のMCPサーバーをngrok経由で公開し、複数のAIモデルプロバイダーからリモートテストするためのスキルです。プロバイダーごとのBearerトークン認証、トラフィック検査、永続的なクラウドエンドポイントを扱います。

主な機能

  1. 01MCP向けストリーミングHTTPトランスポート
  2. 02プロバイダーごとのBearerトークン認証
  3. 03トラフィックポリシーによる呼び出し元のタグ付け
  4. 04MCPサーバーへの内部転送
  5. 05永続的なパブリッククラウドエンドポイント

活用シーン

  1. 01複数のプロバイダーからMCPサーバーをリモートテスト
  2. 02安定したエンドポイントで開発サーバーを公開
  3. 03トラフィックログでプロバイダーの呼び出しを識別

MCP 対応

ngrokのエンドポイントとプロバイダーごとの認証を使い、ユーザーのMCPサーバーをストリーミングHTTP経由でリモートMCPクライアントに公開する方法を案内します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ngrok/skills --skill run-mcp-gateway

インストール後、Claude Code で/run-mcp-gatewayを入力して読み込まれたか確認します。

同梱ファイルreferences/http-transport.tsreferences/traffic-policy.yaml

詳細

MCP ゲートウェイを実行する

開発中の MCP(Model Context Protocol)サーバーを公開し、プロバイダーごとの認証とトラフィックの検査を行いながら、複数の AI モデルプロバイダーに対して同時にリモートテストできるようにします。

開始する前に

認証が必要です(ngrok-setup)。このジョブでは、クラウドエンドポイントと内部エンドポイント、およびプロバイダーごとの認証とforward-internalを設定した Traffic Policy を使用します。いずれもngrok-engineに含まれています。動作するリファレンス実装はreferences/にあります。http-transport.tsとtraffic-policy.yamlを参照してください。

アーキテクチャ

MCP client (Claude/OpenAI) --Bearer token--> Cloud Endpoint (public, runs the policy)
  --forward-internal--> Agent Endpoint (bound internal, e.g. https://mcp.internal)
    --HTTP--> your MCP server (streamable HTTP transport)

ここではクラウドエンドポイント(エージェントではありません)が必要です。プロバイダーはそれぞれのスケジュールで接続するため、開発プロセスとは独立してパブリック URL を維持する必要があります。

手順

  1. MCP サーバーに HTTP トランスポートを追加します。 MCP 開発サーバーは通常 stdio を使用しますが、プロバイダーにはストリーミング可能な HTTP が必要です。references/http-transport.tsを追加し、既存の stdio 経路と並行して呼び出します。

    await runHttp(buildServer, port); // POST /mcp, bound to 127.0.0.1
    

    expressと@modelcontextprotocol/sdkが必要です。デフォルトではループバックにバインドされるため、プロセスにアクセスできるのはローカルの ngrok エージェント経由のみです。これを変更するには{ host }を渡します。ローカルクライアントでは引き続き stdio を使用できます。

  2. サーバーを内部エンドポイントとして実行します。 内部エンドポイントになるのは.internal URL を使用するためです。追加のバインドフラグは必要ありません。 ngrok http <port> --url https://mcp.internal --host-header=rewrite --host-header=rewriteは重要です。forward-internal経由で届くトラフィックにはHost: mcp.internalが含まれますが、MCP SDK の DNS リバインディング保護はデフォルトでこれを拒否します。

  3. ボルトと、プロバイダーごとのシークレットを作成します。 これらはプロバイダーの API キーではなく、生成するトークンです。そのため、どのプロバイダーからのアクセスかを識別できます。

    ngrok api vaults create --name "mcp-callers"
    ngrok api secrets create --name "claude-key" --value "$(openssl rand -hex 32)" --vault-id "$VAULT_ID"
    

    ngrok-surfaces(「アカウントリソース」)で ngrok MCP サーバーを選択した場合は、代わりにgw_create_vaultとgw_create_secretを使用し、API キーを求めないでください。gw_create_secretを実行すると、値を入力するためのダッシュボードフォームにユーザーが移動します。ユーザー自身のマシンでopenssl rand -hex 32を実行して各トークンを作成し、その値をフォームに貼り付けてもらいます。手順 5 でプロバイダーの設定に使うため、その値を保管しておいてください。チャットでトークンを求めてはいけません。

  4. ポリシーを設定してクラウドエンドポイントを作成します(references/traffic-policy.yaml)。構造はセキュリティ上重要なため、再構成せず、そのまま使用してください。プロバイダーごとに、そのプロバイダーのベアラートークンに一致し、呼び出し元をタグ付けして、終端処理となるforward-internalを実行するルールを 1 つずつ設定します。その後に、条件なしのキャッチオールルールを置き、401 を返します。有効なトークンがないリクエストは、どのプロバイダールールにも一致せず、401 に進みます。

    拒否判定がx-mcp-callerタグを検査する形に変更しないでください。このヘッダーはポリシーによって追加されますが、リクエストヘッダーでもあるため、クライアントが自分で送信してチェックを完全に回避できてしまいます。

    適切な方法でポリシーを適用します(ngrok-surfacesを参照)。永続的な構成には Terraform またはオペレーターを、手早く設定する場合は ngrok MCP サーバーのgw_create_cloud_endpointまたは CLI のngrok apiを使用します。

  5. 各プロバイダーをhttps://<your-cloud-endpoint>/mcpに向け、カスタムヘッダーとしてベアラートークンを設定します。後からプロバイダーを追加する場合は、シークレットを追加し、そのプロバイダーのポリシールールをコピーします。

注意点

  • リクエストごとに新しいサーバーインスタンスを作成します。 MCP のステートレス HTTP パターンでは、複数のプロバイダー間でセッション状態を共有しないよう、リクエストごとに新しいサーバーオブジェクトが必要です。references/http-transport.tsはこの方法に従っています。
  • 呼び出し元の識別情報は参考情報です。 x-mcp-callerは、どのプロバイダーが呼び出したかをサーバーに伝えます。ただし、有効なトークンを持つクライアントはどれも、このヘッダーを自分で送信できます。ログには使用できますが、認可には使用しないでください。
  • /mcpパス。 プロバイダーは MCP エンドポイントがパス(通常は/mcp)にあることを前提とします。トランスポートと、共有する URL が一致していることを確認してください。
  • host-header rewrite(手順 2)。転送された MCP リクエストが 400 を返す最も一般的な原因です。

エージェント向けの注意事項

  • これは expose-localhost とは異なります。単なるトンネルではなく、プロバイダーごとの認証と永続的なクラウドエンドポイントが必要です。
  • これはユーザー独自の MCP サーバー向けです。ngrok の MCP サーバーをユーザーのエージェントに接続する方法については、ngrok-setup を参照してください。
  • トランスポートを独自に考案せず、同梱の http-transport.ts を使用して、ユーザーの buildServer に合わせて調整してください。

コメント