Guide · Agent skill
How to use the API Gateway Remote MCP Server agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The API Gateway Remote MCP Server skill teaches an AI agent how to turn a REST API already running on Google Cloud API Gateway into a remote Model Context Protocol (MCP) server, so other AI agents can call it as a set of tools. This guide explains what the skill does, how to install it as an agent skill, how to ask for it in plain language, and what you need before it can deploy anything. The feature is in Public Preview, so read the limitations section before using it in production.
API Gateway Remote MCP Servergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download and install the ZIP. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills instead.
- 2Install the local tools. Update the Google Cloud CLI with gcloud components update and install PyYAML for the validator script with pip, using the pinned range from the skill.
- 3Authenticate and select a project. Log in with gcloud auth login and gcloud auth application-default login, then set your project. Confirm an active billing account is linked to it.
- 4Enable the required APIs. Enable apigateway, servicemanagement and servicecontrol on the project. Add apihub or agentregistry only if you plan to use discovery.
- 5Ask for the task in plain language. Describe what you want, such as migrating a spec or securing tools/list, and name the API or file involved so the agent can find it.
- 6Validate and deploy. Let the agent annotate the OpenAPI 3.x spec, run the validator, and deploy the API config. Then check tools/list and tools/call against the /mcp endpoint.
What is an agent skill, and what does this one do?
An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches the skill's description. This skill is for backend and platform work: it guides the agent through configuring Google Cloud API Gateway so that it serves a POST /mcp endpoint at your gateway's host name.
The endpoint translates MCP JSON-RPC 2.0 requests (initialize, notifications/initialized, tools/list and tools/call) into normal HTTP REST requests to your backend. Existing authentication and quota policies on the gateway still apply.
- Annotates OpenAPI 3.x specs with x-google-api-management.mcp and x-google-mcp-tool
- Migrates OpenAPI 2.0 specs to OpenAPI 3.x, which MCP requires
- Secures the tools/list response with a JWT or an API key
- Connects Google ADK (McpToolset) and discovery in API hub and Agent Registry
- Helps diagnose MCP JSON-RPC errors such as -32601, -32602 and -32000
Check the requirements before you install
The skill can write configuration, but deployment needs a real Google Cloud environment. Set this up first, because the agent will stop at these points otherwise.
You need the Google Cloud CLI, updated to the latest version, and Python 3.10 or later with PyYAML for the local validator script. You also need a Google Cloud project with an active billing account linked to it. API Gateway has a free monthly allowance of API calls per billing account, but an active billing account is still required to deploy. Calls above the allowance and network data transfer out are charged, and the source points to the API Gateway pricing page for current prices.
The skill's guide lists the APIs to enable (apigateway, servicemanagement and servicecontrol) and the IAM roles needed, such as API Gateway Admin and Service Usage Admin. Optional features need API hub or Agent Registry access and Google ADK.
- Google Cloud CLI (gcloud), updated to the latest version
- Python 3.10 or later, plus PyYAML for scripts/validate_mcp_openapi.py
- A Google Cloud project with an active billing account
- Enabled APIs: apigateway, servicemanagement, servicecontrol
- Optional: apihub and agentregistry, Google ADK, API hub or Agent Registry access
pip install "PyYAML>=6.0,<7.0"
gcloud components update
gcloud auth login
gcloud auth application-default login
gcloud config set project {project_id}
gcloud services enable apigateway.googleapis.com servicemanagement.googleapis.com servicecontrol.googleapis.com --project={project_id}How do you install the skill?
Download the skill ZIP from this page and unzip it into one of two locations. Use ~/.claude/skills/ to make the skill available across your projects, or use a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps instead of the file system, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you ask the agent to use it?
You do not need a special command. The agent loads the skill when your request matches its description. Describe the outcome you want in plain language and name the part of MCP or API Gateway involved.
Requests that match the skill's described use cases include migrating an OpenAPI 2.0 spec to OpenAPI 3.x for MCP, adding x-google-mcp-tool annotations to operations, locking down tools/list with a JWT or API key, connecting Google ADK's McpToolset to your gateway, and debugging an MCP error code.
- Migrate this Swagger 2.0 file so API Gateway can serve it as an MCP server.
- Annotate the orders API operations with x-google-mcp-tool names and descriptions, and hide the admin routes from MCP.
- Secure tools/list on my gateway with a JWT and make sure the JWT is in the root security list.
- Connect my Google ADK agent to the /mcp endpoint of my gateway using McpToolset.
- My MCP client returns -32601 when it calls tools/list. Help me find the cause.
What does the agent do step by step?
The skill tells the agent to read its attribution reference before running any gcloud, REST API or MCP command. Terminal gcloud commands are prefixed with a CLOUDSDK_METRICS_REQUEST_ATTRIBUTION environment variable that identifies the skill and carries no user data. The skill notes that gcloud config set should not be used for this, because it would persist beyond the task.
The agent then annotates your OpenAPI 3.x document, validates it with the bundled validator script, deploys the spec with gcloud api-gateway api-configs create, and checks the endpoint with curl. Keep all MCP operations in one OpenAPI document, because if an API config has several documents, API Gateway serves the MCP tools of only one of them.
- Keep MCP operations in a single OpenAPI document per API config
- Give every operation an operationId, and keep tool names to letters, digits, underscores, dots and hyphens
- Check each tool's inputSchema in tools/list after deployment
- Use the /mcp path at the host root, not under a base path
gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(defaultHostname)"Examples of what you can build
The most direct use is exposing an existing internal API to an agent without rewriting the service. The skill's guidance on tool names and descriptions helps an agent choose the right tool, and its migration guidance helps teams that still have OpenAPI 2.0 files.
- An internal orders or inventory API exposed as a handful of read and write tools for an ADK agent
- A legacy Swagger 2.0 definition migrated to OpenAPI 3.x so MCP clients can see its operations
- A tools/list endpoint protected with a JWT, with admin routes kept off MCP but still secured for REST
- A registered MCP server that appears in API hub after the API Gateway project is attached to API hub
Safety notes: scripts and network access
This skill runs scripts and uses the network. The bundled scripts/validate_mcp_openapi.py checks your OpenAPI MCP annotations locally. The other commands the agent runs call Google Cloud and your gateway, so they change real resources in your project.
Review the commands the agent proposes before it runs deployment or IAM changes, and use the most restrictive role for each step, as the skill's IAM guidance advises. Do not apply this skill to Apigee X proxy bundles, outbound LLM model routing or GKE Gateway API, because the skill says it does not cover them.
- Read the proposed gcloud commands before they run
- Grant the least-privileged IAM role for each step
- tools/list is unauthenticated by default, so set a security scheme on it
- x-google-mcp-tool: false hides a route from MCP only; keep REST security on admin routes
What people use it for
- Give an AI agent controlled access to an existing REST API on Google Cloud API Gateway without changing the backend
- Move a Swagger 2.0 definition to OpenAPI 3.x so its operations can be exposed as MCP tools
- Build a Google ADK agent that connects to a remote MCP endpoint through McpToolset
- Hide internal or admin operations from agents while keeping them protected for regular REST callers
Frequently asked questions
Is the API Gateway Remote MCP Server skill free?
The skill itself is licensed under Apache-2.0. Running it requires a Google Cloud project with an active billing account, and API Gateway has a free monthly allowance of API calls per billing account. Calls above that allowance and network data transfer out are charged, so check the current API Gateway pricing page.
What do I need to install before using this skill?
You need the Google Cloud CLI updated to the latest version, Python 3.10 or later with PyYAML, a Google Cloud project with billing enabled, and the apigateway, servicemanagement and servicecontrol APIs enabled. Deployment also needs IAM roles such as API Gateway Admin and Service Usage Admin.
Where do I put the skill so my agent can find it?
Unzip the downloaded ZIP into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside a project for a project-only install. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Does this skill work with OpenAPI 2.0 files?
Not directly. MCP is not supported for OpenAPI 2.0, so the skill tells the agent to migrate the spec to OpenAPI 3.0.x or 3.1.x first. It never adds MCP extensions to a 2.0 spec.
Why does my MCP client return error -32601 or -32000?
The skill includes a troubleshooting reference for MCP JSON-RPC errors, including -32601, -32602 and -32000. Ask the agent to diagnose the error code and check your /mcp endpoint with curl, since the reference covers the expected request lifecycle.
Is this a good alternative to Apigee or GKE Gateway API for agent tools?
It is designed for REST APIs already on Google Cloud API Gateway. The skill says it does not cover Apigee X proxy bundles, outbound LLM model routing or GKE Gateway API, so use a different approach for those.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits backend and platform engineers who already run REST APIs on Google Cloud API Gateway and want AI agents to call them, especially teams migrating OpenAPI 2.0 specs or building with Google ADK. It is a poor fit for production systems that cannot accept Public Preview limits and changing behaviour, or for anyone without a Google Cloud project and billing account.
Download the skill