Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Model Context Protocol を構成する

このドキュメントでは、リモート 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} と一致し、仕様全体で一意である必要があります。
説明: すべてのツールは、空でない説明（オペレーションの説明、概要、オーバーライドから取得）に解決する必要があります。解決可能な説明のないオペレーションは拒否されます。
Security: tools/list の認証を構成する場合は、components.securitySchemes で定義された JWT セキュリティスキームを 1 つだけ指定する必要があります。公開プレビューでは、tools/list の API キーセキュリティはサポートされていません。

認証モデル

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

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

MCP を構成する手順

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

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

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

2. OpenAPI 仕様を更新する

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

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

ドキュメントレベルで x-google-api-management に mcp フィールドを追加して、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

グローバルに有効にすると、対象となるすべてのオペレーション（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 キーはサポートされていません。

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

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

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

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"}
  }
}'

ハンドシェイクの確認応答

初期化を確認します。ゲートウェイは 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"}'

ツールの検出

使用可能なツールを一覧表示します。

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 ヘッダーとして挿入します。

トランスコードされたバックエンドリクエストは、バックエンドサービスへの直接 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 指標とログを生成します。リクエストパス（通常は /mcp で終わる）を検査するか、カスタム指標を構成することで、MCP トラフィックと標準の REST トラフィックを区別できます。

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`	ツール名が見つかりません。クライアントキャッシュをクリーンアップするか、デプロイを確認します。
無効なツールの引数	`-32602`	`200`	引数がないか、無効です。`body` キーのネストを確認します。
本文が長すぎる	`-32000`	`200`	レスポンスペイロードがサイズ上限を超えました。
Transport body が大きすぎる	なし	`413`	未加工の HTTP リクエストの本文がゲートウェイの転送上限を超えています。
サーバーエラー	`-32000`	`200`	解析できないバックエンドレスポンス。ログを確認します。
未承認 / 禁止	なし	`401`/`403`	認証エラーが発生しました。レスポンスには、保護されたリソースメタデータを指す `WWW-Authenticate` ヘッダーが含まれています。

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