api-gateway-mcp-server

API Gateway リモート MCP サーバー（パブリック プレビュー）

このスキルでは、Google Cloud API Gateway 上の新規または既存の REST API を、リモートの Model Context Protocol（MCP）サーバー（POST https://{default_hostname}/mcp、パブリック プレビュー）に変換します。OpenAPI 3.x（3.0.x または 3.1.x）の仕様に x-google-api-management.mcp と x-google-mcp-tool を付与することで、API Gateway は MCP JSON-RPC 2.0 リクエスト（initialize、notifications/initialized、tools/list、tools/call）をバックエンドへの標準 HTTP REST リクエストに変換し、既存の認証ポリシーと割り当てポリシーを適用します。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、使用状況のクレジット表記を必ずお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでの実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-mcp-server)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:api-gateway-mcp-server) を追加してください。

前提条件

1. Google Cloud CLI とバリデーターの依存関係をインストールします。
   • Google Cloud CLIをインストールします。その後、gcloud components update で最新バージョンに更新してください。古い CLI では、OpenAPI 3.x API 構成のアップロードに失敗することがあります。
   • ローカルの OpenAPI MCP バリデーター スクリプト用に、Python 3.10 以降と PyYAML をインストールします。

     pip install "PyYAML>=6.0,<7.0"
     

2. 環境を認証します。
   • ローカル CLI セッション：gcloud auth login
   • アプリケーションのデフォルト認証情報（SDK／ADK）：gcloud auth application-default login
3. プロジェクトを選択または作成し、課金を確認して、サポートされているゲートウェイのロケーションを選びます。
   • 既存のプロジェクトを選択（gcloud config set project {project_id}）するか、新しいプロジェクトを作成します（gcloud projects create {project_id}）。
   • {project_id} に有効な課金アカウントがリンクされていることを確認してください。API Gateway では、各課金アカウントに API 呼び出しの月間無料枠が用意されていますが、デプロイには有効な課金アカウントが必要です。無料枠を超える呼び出しとネットワークのデータ転送には料金がかかります。最新の料金については、API Gateway の料金をご覧ください。
   • ゲートウェイのコマンドでは、デフォルトの --location として us-central1 を使用してください。その他のサポート対象リージョンについては、API Gateway のデプロイモデルをご覧ください。
4. 必要な Google Cloud API を有効にします。

   gcloud services enable \
     apigateway.googleapis.com \
     servicemanagement.googleapis.com \
     servicecontrol.googleapis.com \
     --project={project_id}
   

   API hub の探索（任意）を行う場合は、API hub ホストプロジェクトで API hub API を有効にします：gcloud services enable apihub.googleapis.com --project={hub_project_id}。Agent Registry へのクエリ（任意）を行う場合は、さらに gcloud services enable agentregistry.googleapis.com --project={project_id} を実行します。
5. IAM ロールを確認します（各手順で、最も制限の厳しいロールを使用してください）。
   • API、API 構成、ゲートウェイを作成および更新するには、{project_id} に API Gateway 管理者（roles/apigateway.admin）が必要です。gcloud services enable コマンドを実行するには、そのプロジェクトでサービス使用状況管理者（roles/serviceusage.serviceUsageAdmin）が必要です。
   • API 構成でゲートウェイのサービス アカウントを参照するには、{gateway_sa_name}@{project_id}.iam.gserviceaccount.com にサービス アカウント ユーザー（roles/iam.serviceAccountUser）が必要です。
   • Cloud Run バックエンドの場合、ゲートウェイのサービス アカウントにサービス上の Cloud Run 起動元ロール（roles/run.invoker）を付与します。
   • 呼び出し元のサービス アカウントとしてテスト用 ID トークンを発行するには、{caller_sa_email} にサービス アカウント トークン作成者（roles/iam.serviceAccountTokenCreator）が必要です。
   • 参照：開発環境を構成する。

判断マトリックス：MCP サーバーの構成とクライアントの統合

タスク	必要な仕組み	重要なガードレール	詳細なリファレンス
OpenAPI 2.0（swagger: "2.0"）を移行する、または MCP 用の OpenAPI 3.x を作成する	ルートの x-google-api-management.mcp ＋ 名前付き backends ＋ オペレーションレベルの x-google-mcp-tool	OpenAPI 2.0 の仕様に MCP 拡張機能を追加してはいけません。理由： OpenAPI 2.0 は MCP に対応していません。OpenAPI 3.0.x または 3.1.x を使用し、gcloud api-gateway api-configs create で仕様をデプロイしてください。すべての MCP オペレーションは 1 つの OpenAPI ドキュメントにまとめてください。API 構成に複数のドキュメントがある場合、API Gateway が提供する MCP ツールはそのうち 1 つのドキュメントのものだけです。	OpenAPI 2.0 から 3.x への移行
LLM のツール選択に合わせて、ツール名、説明、スキーマを最適化する	x-google-mcp-tool（name、description、false）＋ 説明を記述した requestBody プロパティ	MCP の有無にかかわらず、すべてのオペレーションに operationId が必要です。公開するすべてのツールは、[A-Za-z0-9_.-]{1,128} に一致する一意の名前（x-google-mcp-tool.name、またはそれがない場合は operationId）、空でない説明、空でないレスポンスボディを持つ必要があります（HTTP 204 はサポートされていません）。ツールにできるのは GET、POST、PUT、PATCH、DELETE オペレーションのみで、ゲートウェイが提供できるツールは最大 1,000 個です。API Gateway は API 構成の作成時に複雑なネストされたスキーマを拒否しますが、単純なネストされたオブジェクトのボディは使用できます。OpenAPI 3.1 では、API Gateway が type: ["string", "null"] のような型のリストも拒否するため、各スキーマの type は 1 つにしてください。各プロパティの説明を記述し、デプロイ後に tools/list で各ツールの inputSchema を確認してください。	OpenAPI エージェントツールオプティマイザー
tools/list を保護し、内部用／管理用ルートを非表示にする	x-google-api-management.mcp.tools-list.security（JWT または API キースキームを正確に 1 つ指定。JWT スキームはルートの security にも記載）＋ x-google-mcp-tool: false	tools/list はデフォルトでは認証されません。JWT スキームを 1 つ指定するか、x-api-key ヘッダーで送信する API キースキームを 1 つ指定できます。API Gateway は、JWT の tools-list.security スキームがルートの security リストにない構成を拒否します。また、このルートエントリーにより、独自の security を持たないすべての REST オペレーションにも JWT 認証が必要になります。ルートリストにすでに API キースキームがある場合は、JWT を同じ要件オブジェクトに追加してください（AND）。API Gateway は API キーを含む代替（OR）要件をサポートしていません。mcp オブジェクト（tools-list 用）を設定すると、対象となるすべてのオペレーションで MCP も有効になります。そのため、エージェントに使用させてはいけないオペレーションは、それぞれ明示的に対象外にしてください。x-google-mcp-tool: false がルートを非表示にするのは MCP からのみです。管理用ルートでは REST の security を維持してください。	OpenAPI 2.0 から 3.x への移行
Google ADK（McpToolset）を接続し、API hub／Agent Registry で検出する	McpToolset（StreamableHTTPConnectionParams）＋ API hub へのプロジェクトのアタッチ	別途登録する必要はありません。API Gateway プロジェクトを API hub にアタッチすると、MCP サーバーが API hub に {your_api} (MCP) として表示され、Agent Registry にも自動的に表示されます。	ADK と API Hub での検出
/mcp の JSON-RPC ライフサイクルを検証し、-32601／-32602／-32000 エラーのトラブルシューティングを行う	MCP-Protocol-Version: 2025-11-25 を指定した POST https://{default_hostname}/mcp	/mcp はホストのルートに配置してください。servers のベースパス（/v2 など）が適用されるのは REST パスのみであり、{basepath}/mcp は HTTP 404 を返します。JSON リクエストボディは params.arguments.body の下にネストしてください（{"body": {...}}）。1 つの構成で x-google-api-management.mcp と x-google-model-router を併用してはいけません。理由： API Gateway では、同じ API 構成内で MCP とモデルルーティングを併用できません。	MCP の検証とトラブルシューティング

実行ワークフローと検証ループ

1. OpenAPI 3.x 仕様にアップグレードして注釈を付けます：
   • このスキルの参照資料に変換ルールがあります。Swagger 2.0 Construct Conversion Map では Swagger 2.0 の各構成要素を扱い、Complete Converted Example では Google ID トークン方式を使った完成済みの仕様を示しています。他の情報源を検索する前に、これらを使用してください。
   • OpenAPI 2.0 to 3.x Migration と OpenAPI Agent Tool Optimizer に従って、openapi を 3.0.x または 3.1.x のバージョン（例では 3.0.4 を使用）に設定し、サポートされていない OpenAPI 2.0 フィールド（x-google-allow）を削除し、x-google-api-management.backends（jwtAudience または disableAuth を含む）を定義し、x-google-api-management.mcp.tools-list.security を JWT 方式または API キー方式のいずれか一つだけで設定し（API キー方式と同じ要件オブジェクト内に JWT 方式も追加して、ルートの security リストにも JWT 方式を追加します）、各ツールを いつ、なぜ 呼び出すかを記載した x-google-mcp-tool の説明を作成し、管理用ルートは x-google-mcp-tool: false で対象外にします。
   • デプロイする前に、以下の各点を記載した短い要約をユーザーに提示し、承認を得てください。
     • OpenAPI 2.0 は MCP でサポートされていないため、仕様を OpenAPI 3.x に変換したこと。
     • ツールとして公開したオペレーションと、x-google-mcp-tool: false で対象外にしたオペレーション。対象外のオペレーションは REST のままです。
     • tools/list が JWT 方式を使う場合、ルートの security エントリにより、独自の security を持たないすべての REST オペレーションで JWT が必要になります。ゲートウェイは JWT を持たない REST 呼び出し元を拒否します。
     • MCP エンドポイントは https://{default_hostname}/mcp であり、仕様で servers のベースパスを設定していてもホストのルートにあります。
     • 適用される制限：ツールにできるのは GET、POST、PUT、PATCH、DELETE オペレーションのみであること、ゲートウェイが提供できるツールは最大 1,000 個であること、リクエストパラメーターはプリミティブ型である必要があること、API Gateway は API config の作成時に複雑な入れ子のスキーマと OpenAPI 3.1 の型リスト（type: ["string", "null"] など）を拒否すること、ツールは HTTP 204 を返せないこと、MCP はステートレスで UTF-8 テキスト応答のみをサポートすること。
   • ユーザーが変換済みの仕様またはアドバイスのみを求め、デプロイを行わない場合も、同じ点を伝えてください。
   • 既存のゲートウェイで HTTP 500 Failed to call Service Control Quota が発生しないよう、API config 間で x-google-api-management.metrics のクォータ指標名を正確に維持してください。
2. API config を作成する前に、決定的な MCP OpenAPI 検証ループを実行します：
   • {candidate_openapi_spec} に対して scripts/validate_mcp_openapi.py を実行します。

     python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec}
     

   • scripts/validate_mcp_openapi.py が終了コード 1（status: "FAIL"）を返した場合は、{candidate_openapi_spec} で報告されたすべてのエラーを修正します（OpenAPI 2.0 構文、x-google-allow、パスレベルの x-google-mcp-tool、未定義のバックエンド名、operationId のないオペレーション、説明の不足、無効または重複したツール名、予約済みの x-google- プレフィックスを持つヘッダーパラメーター、oauth2 の JWT 方式でも apiKey 方式でもない tools-list.security スキーム、ルートの security リストにない JWT の tools-list.security スキーム、API キーを含む代替（OR）セキュリティ要件、MCP 仕様内の x-google-model-router オペレーションなど）。その後、スクリプトが終了コード 0（status: "PASS"）を返すまで再実行します。終了コード 2 の場合は、stderr に出力されたファイルパスまたは YAML 構文エラーを修正してください。
   • 警告をすべて確認してください（HTTP 204 応答、プリミティブ型でないリクエストパラメーター、mcp オブジェクトによってデフォルトで公開されるオペレーションなど）。修正するか、そのままにする理由をユーザーに伝えてください。
3. API（新規の場合）を作成し、API config を作成して、ゲートウェイをデプロイし、マネージドサービスを有効にします（本番ゲートウェイを更新する前に、人による承認を得てください）：

   gcloud api-gateway apis create {api_id} --project={project_id}
   
   gcloud api-gateway api-configs create {config_id} \
     --api={api_id} \
     --openapi-spec={candidate_openapi_spec} \
     --backend-auth-service-account={gateway_sa_name}@{project_id}.iam.gserviceaccount.com \
     --project={project_id}
   
   gcloud api-gateway gateways update {gateway_id} \
     --api={api_id} \
     --api-config={config_id} \
     --location={region} \
     --project={project_id}
   
   gcloud services enable $(gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)") --project={project_id}
   

   (新しいゲートウェイを作成する場合は、gateways update の代わりに gcloud api-gateway gateways create {gateway_id} ... を実行します。)
   • API ごとに一度に実行する api-configs create は一つにしてください。次の作成を始める前に完了を待ってください。API Gateway が一度に作成できる API config は、API ごとに一つだけです。複雑な API config の作成には最大 10 分かかることがあります。
   • クライアントが他のプロジェクトの API キーを使う場合は、それらの各プロジェクトでもマネージドサービスを有効にしてください。API Gateway は、キーを作成したプロジェクトで API が有効になっていない API キーを拒否します。
4. JSON-RPC 2.0 のライフサイクルを検証し、ADK / API hub に接続します：
   • 仕様で servers のベースパスを設定していても、すべてのプローブを https://{default_hostname}/mcp に送信してください。
   • HTML の 404 Page not found が表示された場合、ゲートウェイが正しくデプロイされていない可能性があります。ゲートウェイの状態が ACTIVE で、直近の作成または更新が完了していることを確認し、設定を変更する前に再試行してください。ゲートウェイの更新中、一部のリクエストは以前の API config に引き続き到達することがあります。JSON の 404（The current request is not defined by this API.）は、有効な config にそのパスが定義されていないことを示します。
   • tools/list で JWT が必要な場合は、x-google-auth.audiences に含まれる audience を指定して Google ID トークンを発行します：gcloud auth print-identity-token --impersonate-service-account={caller_sa_email} --audiences={jwt_audience}。tools/list で API キーが必要な場合は、x-api-key ヘッダーに指定してください。
   • MCP Verification and Troubleshooting に記載された initialize、notifications/initialized、tools/list、tools/call の検証プローブを実行してください。
   • ADK and API Hub Discovery を使って Google ADK（McpToolset）を接続し、Apigee API hub（{your_api} (MCP)）および Agent Registry で自動カタログ検出を検証してください。

デプロイ前チェックリスト

• 仕様のバージョンが openapi: 3.0.x または 3.1.x（swagger: "2.0" ではない）であり、x-google-allow と x-google-model-router が含まれていません。
• python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec} を実行すると、status: "PASS"（終了コード 0）が返されます。
• すべての操作に operationId があり、すべての MCP 操作が 1 つの OpenAPI ドキュメントに含まれています。
• x-google-api-management.mcp.tools-list.security には、1 つのスキームだけが指定されています。ルートの security リストでも参照されている x-google-auth を持つ oauth2 JWT スキーム、または in: header と name: x-api-key を持つ apiKey スキームです。
• tools/list で JWT スキームを使用する場合、独自の security を持たない REST 操作にもその JWT が必要になることをユーザーが把握しています。
• 管理用、ヘルスチェック用、および HTTP 204 のエンドポイントは x-google-mcp-tool: false で対象外に設定されており、対象外にした管理用パスは REST でも保護されています。
• MCP クライアントは https://{default_hostname}/mcp（{basepath}/mcp ではありません）を呼び出し、tools/call の JSON リクエストボディを params.arguments.body 内にネストし、MCP-Protocol-Version: 2025-11-25 を送信します。

リソースのクリーンアップ

テスト環境またはステージング環境の削除後に料金が発生し続けるのを防ぐため、人間の承認を得て、依存関係の順序に従ってゲートウェイ、API 構成、API、サービスアカウントを削除してください。

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}
gcloud iam service-accounts delete {gateway_sa_name}@{project_id}.iam.gserviceaccount.com --project={project_id}