Google Cloud API Gateway MCP: Expose REST APIs as Agent Tools Safely
QUICK ANSWER
Google Cloud API Gateway can now act as a remote Model Context Protocol server in Public Preview. Teams can annotate an existing OpenAPI 3.x API with Google MCP extensions and expose eligible REST operations as MCP tools on the gateway's /mcp endpoint without building a separate MCP server. The gateway translates MCP JSON-RPC calls into the existing REST operation and keeps that operation's configured authentication, quota and logging path. Production teams should still treat the feature as Pre-GA, explicitly choose which operations become tools, secure tools/list with JWT when tool metadata should not be public, and test current preview limits before relying on the integration.
A team has working REST APIs but is duplicating routing, authentication and quotas in a separate MCP server
An agent needs to call existing Cloud Run or REST operations through a standard MCP interface
Tool names and input schemas are visible through tools/list even though the team expected discovery to be private
An OpenAPI 2.0 definition cannot enable the new MCP configuration
An MCP design depends on streaming, resources, prompts or another capability that API Gateway Public Preview does not currently support
Possible causes
API Gateway now derives MCP tools from annotated OpenAPI 3.x operations and translates tools/call requests into the existing REST path
OpenAPI 2.0 is not supported for MCP, so older gateway specifications need migration before enablement
tools/list is unauthenticated by default unless JWT security is configured for discovery
tools/call continues to enforce the underlying REST operation's configured authentication
Public Preview currently supports a bounded MCP surface and has explicit transport, payload, tool-count and model-routing limitations
HOW TO FIX IT
Work from the safest step to the harder repair.
Step 1. Inventory the REST operations an agent genuinely needs. Expose the smallest useful set instead of enabling every eligible operation by default.
Step 2. Confirm the gateway specification is OpenAPI 3.0.x or 3.1.x. Google documents that OpenAPI 2.0 is not supported for MCP.
Step 3. Enable MCP with x-google-api-management.mcp and use x-google-mcp-tool at operation level when an operation needs a custom tool name, description or opt-out.
Step 4. Write tool descriptions for model selection quality: explain when and why the agent should call the tool, not merely what the endpoint returns.
Step 5. Decide whether tool discovery may be public. If not, configure tools/list with exactly one JWT security scheme; Google states API keys cannot secure tools/list in the current preview.
Step 6. Keep the underlying REST operation's authentication and authorization least-privileged. A successful MCP handshake must not be treated as authorization to call every backend operation.
Step 7. Deploy to a non-production gateway first and verify initialize, tools/list and tools/call against representative success and failure cases.
Step 8. Test preview constraints before migration: no OpenAPI 2.0, no stdio transport, no resources or prompts, no streaming/long-running tool calls, no JSON-RPC batch arrays, text-only responses, and a maximum of 1,000 tools per gateway.
Step 9. Do not combine MCP and Model Routing in the same API config because Google documents them as mutually exclusive in the current preview.
Step 10. Review logs, quotas, error translation and backend authorization after deployment, then checkpoint and roll out gradually with a reversible configuration change.
Need the actual code? Go to GenesisCodeDoctor.com to search the Code Store or request code for the exact platform, error, and repair you are working on.
1. Is the API already described in OpenAPI 3.x? If no, migrate and validate the specification before adding MCP annotations.
2. Should every eligible operation become a tool? If no, use per-operation x-google-mcp-tool controls and keep non-agent operations out of the tool surface.
3. May anyone discover tool names and schemas? If no, protect tools/list with JWT before production exposure.
4. Does the workflow require streaming, resources, prompts, binary responses or model routing in the same config? If yes, stop and redesign around the current preview boundaries.
5. Does the underlying REST operation enforce the correct identity and authorization? If no, fix backend access control before exposing it through MCP.
6. Did staging verification pass for initialize, tools/list, tools/call, quotas, logs and failure paths? If yes, deploy gradually and monitor.
REPAIR FLOW
A visual path from symptom to verified production.
Observe→
Protect→
Isolate→
Repair→
Test→
Publish→
Verify live
BEFORE YOU PASTE CODE
Protect the working site first.
Keep production credentials out of prompts, examples, logs and generated configuration.
Use least-privilege JWT, OAuth or API-key policies on the underlying REST operations and test authorization failures explicitly.
Keep tool descriptions free of secrets and internal data that should not appear in discovery metadata.
Treat MCP enablement as an API-surface change: review the diff, test it, monitor it and keep a rollback path.
STOP AND GET HELP WHEN
Do not turn a repair into a larger outage.
Do not describe API Gateway MCP as generally available while Google labels it Public Preview / Pre-GA.
Do not expose sensitive operation names or input schemas through unauthenticated tools/list when that metadata should remain private.
Do not assume API-key protection on backend operations also secures tools/list; Google documents JWT as the supported discovery-authentication method in this preview.
Do not migrate an OpenAPI 2.0 spec by mechanically changing only the version line; validate the full OpenAPI 3.x conversion and gateway behavior.
Do not design around streaming, MCP resources, prompts or binary tool responses until current Google documentation says those capabilities are supported.
Do not give an agent broader backend permissions merely because the gateway can expose the operation as a tool.
HOW GENESIS HANDLES IT
Diagnose the exact failure before choosing a repair.
Genesis separates the visible symptom from the underlying technical cause. Run the supported diagnostic first, review the evidence, and then use a matching repair only when the failure is actually verified.
Platform scope
Google Cloud API Gateway · Model Context Protocol · OpenAPI 3.x · Cloud Run · ADK · REST APIs
Category
MCP · API architecture · Agent infrastructure
Last updated
2026-09-25
REPAIR PROFILE
Know the complexity before you edit.
Difficulty
Intermediate
Change risk
Medium
These labels describe implementation complexity and blast radius, not a guaranteed repair time.
AUTHORITATIVE SOURCES
Verify time-sensitive platform details at the source.
Start with a free diagnostic. If Genesis verifies a problem and a compatible treatment exists, continue to the matching Code Store product or repair path. If you cannot find the exact code you need, request it at GenesisCodeDoctor.com rather than forcing a generic snippet into the wrong platform.
