Model Context Protocol を構成する

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前サービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

このドキュメントでは、リモート Model Context Protocol（MCP）サーバーとして機能するように API Gateway を構成する方法について説明します。

始める前に

• API に有効な OpenAPI 3.x 仕様があることを確認します。MCP は OpenAPI 2.0 ではサポートされていません。
• API Gateway の基本を理解していることを確認します。

構成の検証

OpenAPI 仕様をアップロードすると、API Gateway は MCP 構成に対して次の検証を行います。

• 場所: x-google-mcp-tool 拡張機能は、個々のオペレーション レベルでのみ指定する必要があります。
• HTTP メソッド: GET、POST、PUT、PATCH、DELETE オペレーションのみを MCP ツールとして公開できます。
• ツール名: ツール名は [A-Za-z0-9_.-]{1,128} と一致し、仕様全体で一意である必要があります。
• 説明: すべてのツールは、空でない説明（オペレーションの説明、概要、オーバーライドから取得）に解決される必要があります。解決可能な説明のないオペレーションは拒否されます。
• セキュリティ: tools/list の認証を構成する場合は、components.securitySchemes で定義されたセキュリティ スキームを 1 つだけ指定する必要があります。スキームは、JWT スキームまたは API キー スキームにできます。JWT スキームを使用する場合は、仕様の最上位の security 要件でも名前を指定する必要があります。

認証モデル

API Gateway は、呼び出された MCP メソッド呼び出しに応じて異なる認証ルールを適用します。

• プロトコルのライフサイクル: initialize メソッドと notifications/initialized メソッドは認証されていません。
• ツール呼び出し（tools/call）: OpenAPI 仕様の基盤となるオペレーションに定義されている認証ポリシーを再利用します。REST エンドポイントを直接呼び出す場合と同じ API キーまたは JWT の要件が適用されます。
• ツール検出（tools/list）: デフォルトでは、このメソッドは認証されていません。ただし、セキュリティのベスト プラクティスとして、tools-list.security を使用してこのメソッドの認証を有効にすることで、ツールの検出を保護することを強くおすすめします。tools/list は、JWT または API キーで認証できます。

MCP を構成する手順

API を MCP ツールとして公開する手順は次のとおりです。

1. 公開するオペレーションを特定する

OpenAPI 仕様を確認し、AI エージェントが使用できるオペレーションを決定します。

2. OpenAPI 仕様を更新する

MCP は、対象となるすべてのオペレーションに対してグローバルに有効にすることも、オペレーションごとに構成することもできます。

グローバルなイネーブルメント

ドキュメント レベルで mcp フィールドを x-google-api-management に追加して、MCP をグローバルに有効にします。

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

注: オペレーションが MCP ツールとして適格になるように、オペレーションにバックエンドが構成されていることを確認します（オペレーション レベルで x-google-backend を使用するか、グローバル デフォルトを使用します）。

グローバルに有効にすると、対象となるすべてのオペレーション（HTTP メソッドとパスに基づく）が MCP ツールとして公開されます。デフォルトでは、ツール名はオペレーションの operationId で、説明はオペレーションの説明または概要です。

オペレーションごとの構成

x-google-mcp-tool を使用して、グローバル設定をオーバーライドしたり、オペレーションを選択的に公開したりできます。

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

x-google-mcp-tool: false を設定することで、グローバルに有効になっているオペレーションをオプトアウトすることもできます。

3. tools/list を認証する（推奨）

デフォルトでは、tools/list メソッド（利用可能なツールを列挙するメソッド）は認証されません。セキュリティのベスト プラクティスとして、x-google-api-management.mcp で tools-list.security を構成して認証を適用することを強くおすすめします。JWT スキームまたは API キー スキームに名前を付けることができます。

次の例では、JWT が必要です。

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

次の例では API キーが必要です。クライアントは x-api-key HTTP ヘッダーでキーを送信する必要があります。tools/list はクエリ パラメータから API キーを読み取りません。有効なキーがないリクエストは、JSON-RPC エラーを受け取り、ツールリストは受け取りません。API キーの作成方法については、API キーを使用するをご覧ください。

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

注: mcp 拡張機能をオブジェクトとして構成すると（たとえば、tools/list の認証を有効にする場合）、対象となるすべてのオペレーションで MCP がグローバルに有効になります。tools/list セキュリティを構成するが、対象となるすべてのオペレーションを公開しない場合は、x-google-mcp-tool: false を設定して、それらのオペレーションを明示的にオプトアウトする必要があります。

4. API 構成を作成してデプロイする

アノテーション付きの仕様から API 構成を作成し、標準フローを使用してゲートウェイにデプロイします。詳細については、ゲートウェイへの API のデプロイをご覧ください。後でツールを変更するには、公開されている MCP ツールを更新するをご覧ください。

5. MCP のサポートを確認する

デプロイが完了したら、ゲートウェイが MCP リクエストを処理していることを確認できます。

Handshake

初期化リクエストを送信して、プロトコルのバージョンと機能を確立します。

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

注: クライアントは、初期化後のすべてのリクエストで MCP-Protocol-Version ヘッダーを送信する必要があります。ヘッダーが存在しない場合、ゲートウェイはバージョン 2025-03-26 にフォールバックします。

確認応答ハンドシェイク

初期化を承認します。ゲートウェイは HTTP 202 Accepted を返します。

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

ツールの検出

利用可能なツールを一覧表示します。tools-list.security を構成した場合は、一致する認証情報を追加します。たとえば、JWT の Authorization: Bearer ヘッダーや API キーの x-api-key ヘッダーなどです。

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

引数が REST リクエストにマッピングされる仕組み

ツールに渡される引数は、OpenAPI 仕様に基づいて、基盤となる REST リクエストにマッピングされます。

• パスとクエリ パラメータ: arguments オブジェクトの最上位プロパティになり、OpenAPI パラメータ名でキー設定されます。
• リクエスト本文: body という名前の単一のプロパティの下にネストされます。たとえば、リソースを作成するには、{"body": {"fieldName": "value"}} を渡します。
• ヘッダー: 最上位プロパティにもなります。ゲートウェイは、バックエンド呼び出しに標準の HTTP ヘッダーとして挿入します。

注: 予約済みのシステム ヘッダーまたは x-google- で始まるヘッダーにパラメータをバインドすることはできません。

コード変換されたバックエンド リクエストは、バックエンド サービスへの直接 REST リクエストと区別できません。バックエンド サービスは、直接の REST 呼び出しと MCP からコード変換された呼び出しをプログラムで区別できません。

ツールを呼び出す

特定のツールを呼び出す。基盤となる REST オペレーションで必要な認証トークンがある場合は、それを含めます。

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

公開されている MCP ツールを更新する

API Gateway の API 構成は不変であるため、既存の API 構成の API 定義を変更することはできません。その結果、tools/list レスポンスはデプロイされた API 構成ごとに静的になります。

公開されている MCP ツールまたは tools/list セキュリティ設定を追加、削除、名前変更、更新するには、新しい API 構成を作成してゲートウェイにデプロイします。

1. オペレーション、operationId 値、サマリー、パラメータ、x-google-api-management.mcp 拡張機能、x-google-mcp-tool 拡張機能など、OpenAPI 3.x 仕様を更新します。

2. 新しい API 構成 ID を使用して新しい API 構成を作成します。

   gcloud api-gateway api-configs create NEW_CONFIG_ID \
       --api=API_ID \
       --openapi-spec=API_DEFINITION \
       --project=PROJECT_ID \
       --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   次のように置き換えます。

   • NEW_CONFIG_ID: 更新された API 構成の新しい ID
   • API_ID: API Gateway API の ID
   • API_DEFINITION: 更新された OpenAPI 3.x 仕様のパス
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID
   • SERVICE_ACCOUNT_EMAIL: 認証が構成されたバックエンドのトークンに署名するために使用されるサービス アカウントのメールアドレス。バックエンドで認証が必要ない場合は、このフラグを省略します。

   詳細については、API 構成を作成するをご覧ください。

3. API を提供する各ゲートウェイを更新して、新しい API 構成を使用します。

   gcloud api-gateway gateways update GATEWAY_ID \
       --api=API_ID \
       --api-config=NEW_CONFIG_ID \
       --location=GCP_REGION \
       --project=PROJECT_ID

   次のように置き換えます。

   • GATEWAY_ID: 更新するゲートウェイの ID
   • GCP_REGION: ゲートウェイがデプロイされているリージョン

   詳細については、ゲートウェイを更新するをご覧ください。

4. tools/list を呼び出して、更新されたツールセットを確認します。リクエストの例については、ツールを検出するをご覧ください。

5. 以前の API 構成を使用するゲートウェイがなくなったら、置き換えられた API 構成を削除します。

   gcloud api-gateway api-configs delete OLD_CONFIG_ID \
       --api=API_ID \
       --project=PROJECT_ID

   OLD_CONFIG_ID は、置き換えられる API 構成の ID に置き換えます。ゲートウェイが API 構成を使用している間は、API 構成を削除しないでください。新しい API 構成で割り当て指標の名前を変更または削除すると、古い API 構成を処理しているゲートウェイは、更新されるまで HTTP 500 エラーを返す可能性があります（割り当ては API 全体に適用されるをご覧ください）。詳細については、API 構成を削除するをご覧ください。

MCP ツールを更新する際は、次のロールアウトとクライアントの動作に注意してください。

• ダウンタイムなしのロールアウト: API Gateway は、ダウンタイムなしでゲートウェイを更新します。新しい API 構成が伝播される間、一部のリクエストが前の API 構成に一時的に到達することがあります。API が複数のゲートウェイまたはリージョンにデプロイされている場合は、各ゲートウェイを個別に更新します。
• クライアント ツールのキャッシュ: API Gateway はステートレス HTTP トランスポートを介して MCP を提供するため、ゲートウェイは notifications/tools/list_changed 通知を出力しません。ゲートウェイの更新が完了したら、ツール定義をキャッシュに保存する MCP クライアントは、tools/list を再度呼び出して、更新されたツールを検出する必要があります。
• API 構成の上限: 各 API の API 構成は 100 個に制限されているため、ゲートウェイを更新した後に、置き換えられた API 構成を削除します。API 構成は 1 つずつ作成します。同じ API の最初の API 構成が完了する前に 2 番目の API 構成を開始すると、一方または両方の構成がゲートウェイで使用できなくなることがあります。詳細については、割り当てと上限をご覧ください。

オブザーバビリティ

MCP リクエストは、標準の API Gateway の指標とログを生成します。MCP トラフィックと標準の REST トラフィックを区別するには、リクエストパス（通常は /mcp で終わる）を検査するか、カスタム指標を構成します。

MCP 障害のトラブルシューティング

MCP は、トランスポート障害とプロトコル障害を区別します。ゲートウェイは、プロトコル エラーとアプリケーション エラーに対して JSON-RPC エラー オブジェクトを含む HTTP 200 を返します。200 以外のレスポンスを返すと、多くの MCP クライアントがトランスポート層で失敗する可能性があるためです。

次の表に、一般的な症状と修正方法を示します。

症状	JSON-RPC コード	HTTP ステータス	意味と一般的な修正
許可されていないメソッドです	なし	405	POST 以外のリクエストが /mcp に到達しました。HTTP POST のみがサポートされています。
JSON 解析エラー	-32700	400	リクエスト本文が有効な JSON ではありません。
方法または ID がないか、無効です	-32600	200	本文は有効な JSON ですが、有効な JSON-RPC リクエストではありません。必須フィールド（jsonrpc、method、id）を確認します。
メソッドがサポートされていない	-32601	200	メソッドがサポート対象外である（例: ping）。
サポートされていないプロトコル バージョン	-32602	200	protocolVersion に、ゲートウェイがサポートしていないバージョンが指定されています。
プロトコル バージョンがありません	-32602	200	initialize パラメータで protocolVersion が省略されているか、文字列ではありません。
不明なツール	-32602	200	デプロイされた API 構成にツール名が見つかりません。クライアント ツールのキャッシュを更新するか、公開されている MCP ツールを更新するをご覧ください。
無効なツール引数	-32602	200	引数がないか、無効です。body キーのネストを確認します。
本文が長すぎます	-32000	200	レスポンス ペイロードがサイズ上限を超えています。
トランスポート本文が大きすぎる	なし	413	未加工の HTTP リクエストの本文がゲートウェイの転送上限を超えています。
サーバーエラー	-32000	200	バックエンド レスポンスを解析できません。ログを確認します。
未承認 / 禁止	なし	401/403	認証エラー。レスポンスには、保護されたリソースのメタデータを指す WWW-Authenticate ヘッダーが含まれます。

バックエンド アプリケーション エラーは通常、バックエンド エラー本文を含む result.isError: true を含む JSON-RPC レスポンス（HTTP 200）として表示されます。

次のステップ

• Model Context Protocol の概要
• OpenAPI 3.x 拡張機能
• OpenAPI 3.x 機能の制限