/api-gateway-mcp-server

name: api-gateway-mcp-server
metadata:
  version: "1.0.0"
  category: AiAndMachineLearning
description: >-
  Configures Google Cloud API Gateway to act as a remote Model Context Protocol
  (MCP) server (Public Preview) that exposes REST APIs as agent tools over
  HTTP (POST /mcp). Use when migrating OpenAPI 2.0 specs
  to OpenAPI 3.x for MCP, annotating specs with x-google-api-management.mcp
  and x-google-mcp-tool, securing tools/list with JWTs or API keys,
  connecting Google ADK (McpToolset) or Apigee API hub and Agent Registry, or
  troubleshooting MCP JSON-RPC errors (-32601, -32602, -32000). Do not use for
  Apigee X proxy bundles, outbound LLM model routing, or GKE Gateway API.

API Gateway Remote MCP Server (Public Preview)

This skill converts new or existing REST APIs on Google Cloud API Gateway into remote Model Context Protocol (MCP) servers (`POST https://{default_hostname}/mcp`, **Public Preview**). By annotating an OpenAPI 3.x (3.0.x or 3.1.x) specification with `x-google-api-management.mcp` and `x-google-mcp-tool`, API Gateway translates MCP JSON-RPC 2.0 requests (`initialize`, `notifications/initialized`, `tools/list`, `tools/call`) into standard HTTP REST requests to your backend while enforcing existing authentication and quota policies.

Prerequisites

1. **Install the Google Cloud CLI and the validator dependency:**

• Install the [Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt). Then update it to the latest version with `gcloud components update`. An old CLI can fail when it uploads an OpenAPI 3.x API config.
• Install Python 3.10 or later and `PyYAML` for the local OpenAPI MCP validator script:

     pip install "PyYAML>=6.0,<7.0"

2. **Authenticate your environment:**

• Local CLI session: `gcloud auth login`
• Application Default Credentials (SDKs / ADK): `gcloud auth application-default login`

3. **Select or create a project, confirm billing, and pick a supported gateway location:**

• Select an existing project (`gcloud config set project {project_id}`) or create one (`gcloud projects create {project_id}`).
• Confirm that an active billing account is linked to `{project_id}`. API Gateway has a free monthly allowance of API calls for each billing account, but you still need an active billing account to deploy. Calls above the allowance and network data transfer out are charged. For current prices, see [API Gateway pricing](https://cloud.google.com/api-gateway/pricing).
• Use `us-central1` as the default `--location` for gateway commands. For the other supported regions, see [API Gateway deployment model](https://docs.cloud.google.com/api-gateway/docs/deployment-model.md.txt).

4. **Enable the required Google Cloud APIs:**

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

For API hub discovery (optional), enable the API hub API in the API hub host project: `gcloud services enable apihub.googleapis.com --project={hub_project_id}`. To query Agent Registry (optional), also run `gcloud services enable agentregistry.googleapis.com --project={project_id}`. 5. **Verify the IAM roles (use the most restrictive role for each step):**

• To create and update the API, API configs, and gateways: API Gateway Admin (`roles/apigateway.admin`) on `{project_id}`. To run the `gcloud services enable` commands: Service Usage Admin (`roles/serviceusage.serviceUsageAdmin`) on that project.
• To reference the gateway service account in an API config: Service Account User (`roles/iam.serviceAccountUser`) on `{gateway_sa_name}@{project_id}.iam.gserviceaccount.com`.
• For a Cloud Run backend: grant the gateway service account the Cloud Run Invoker role (`roles/run.invoker`) on the service.
• To mint test ID tokens as a caller service account: Service Account Token Creator (`roles/iam.serviceAccountTokenCreator`) on `{caller_sa_email}`.
• Reference: [Configure the development environment](https://docs.cloud.google.com/api-gateway/docs/configure-dev-env.md.txt).

Decision Matrix: MCP Server Configuration and Client Integration

| Task | Required Mechanism | Critical Guardrail | Detailed Reference | | --- | --- | --- | --- | | Migrate OpenAPI 2.0 (`swagger: "2.0"`) or author OpenAPI 3.x for MCP | Root `x-google-api-management.mcp` + named `backends` + operation-level `x-google-mcp-tool` | NEVER add MCP extensions to an OpenAPI 2.0 spec. **Rationale:** MCP is not supported for OpenAPI 2.0. Use OpenAPI 3.0.x or 3.1.x, and deploy the spec with `gcloud api-gateway api-configs create`. Keep all MCP operations in one OpenAPI document: if an API config has several documents, API Gateway serves the MCP tools of only one of them. | [OpenAPI 2.0 to 3.x Migration](references/openapi-v2-to-v3-mcp-migration.md) | | Optimize tool names, descriptions, and schemas for LLM tool selection | `x-google-mcp-tool` (`name`, `description`, `false`) + described `requestBody` properties | Every operation MUST have an `operationId`, with or without MCP. Every exposed tool MUST resolve to a unique name that matches `[A-Za-z0-9_.-]{1,128}` (`x-google-mcp-tool.name`, or else the `operationId`), a non-empty description, and a non-empty response body (`HTTP 204` is unsupported). Only `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` operations can be tools, and a gateway serves at most 1,000 tools. API Gateway rejects complex nested schemas when you create the API config, but a simple nested object body works. In OpenAPI 3.1, give each schema one `type`, because API Gateway also rejects a type list such as `type: ["string", "null"]`. Describe each property, and check each tool's `inputSchema` in `tools/list` after you deploy. | [OpenAPI Agent Tool Optimizer](references/openapi-agent-tool-optimizer.md) | | Secure `tools/list` and hide internal/admin routes | `x-google-api-management.mcp.tools-list.secu