使用 Google Cloud API Gateway 将 REST API 转换为 MCP 工具

企业的大多数能力都位于 REST API 之后，而 Agent 无法直接发现这些能力。如今，要让 Agent 调用某个 API，团队通常需要部署并运维一个独立的 MCP 服务器，重新实现其网关已经处理的路由、身份验证和配额逻辑。Model Context Protocol（MCP）已成为 Agent 发现和调用工具的标准方式，Agent Development Kit（ADK）和 Gemini Enterprise 等框架均原生支持该协议。

Google Cloud API Gateway 现在填补了这一空白。在 Public Preview 中，API Gateway 可以充当远程 MCP 服务器：为已部署的 OpenAPI 规范添加注解后进行部署，现有 REST 操作即可作为面向 Agent 的 MCP 工具使用，无需构建、托管或维护单独的服务器。

API Gateway 是 Google Cloud 网关产品线中的轻量级快速入口。如果你的服务运行在 Cloud Run 上，并希望在数分钟内让其 API 获得安全保护、管理能力并向 Agent 开放，这是最快路径。如果需要完整的企业级 API 与 MCP 平台，包括生命周期管理、高级流量策略和商业化功能，请使用 Apigee。若要治理 Agent 对外调用的对象，包括像本文所述的 MCP 服务器，请使用 Agent Gateway。模型路由可为出站 LLM 调用提供一个稳定端点，是 AI 流量另一方向的配套能力。

工作原理

API Gateway 在单一端点上接受标准 MCP JSON-RPC 请求，将每个 tools/call 转码为相应的 REST 请求，应用现有策略，再将响应转换回来。由于转码后的请求与普通 REST 调用没有区别，因此你已为该操作配置的 JWT 或 API Key 身份验证、配额和日志记录都会保持不变——MCP 与 REST 流量完全共享同一条策略路径，同一操作无论通过何种方式调用，都使用同一份配额分配。

1. 为 OpenAPI 规范添加注解。 MCP 要求使用 OpenAPI 3.0.x 或 3.1.x；不支持 OpenAPI 2.0，因此如果你的网关仍在使用 2.0 规范，请先完成迁移。通过 x-google-api-management.mcp 在文档级别启用 MCP，并通过 x-google-mcp-tool 自定义或跳过单个操作。每个暴露的操作都需要后端以及非空描述。

yaml openapi: 3.0.4 info: title: Order Service version: 1.0.0

x-google-api-management: mcp: true # expose this spec's operations as MCP tools backends: orders-backend: address: https://orders-a1b2c3-uc.a.run.app

paths: /orders/{orderId}: get: operationId: getOrderStatus description: Returns the current status, carrier, and ETA for an order. x-google-backend: orders-backend x-google-mcp-tool: name: get_order_status description: "Look up the delivery status and ETA of a customer order. Use this when the user asks where an order is or when it will arrive." parameters: - name: orderId in: path required: true schema: type: string

工具描述是 LLM 判断何时调用工具的主要信号，因此应描述使用该工具的时机和原因，而不仅仅是它会返回什么。

2. 部署网关。 按照常规方式部署 API 配置。API Gateway 会生成具备 MCP 感知能力的配置，并开始在 /mcp 基础路径上提供 MCP 服务，无需额外配置基础设施。

3. 确定哪些人能够发现你的工具。 默认情况下，tools/list 无需身份验证。这在开发阶段较为方便，但也意味着任何发起请求的人都能看到你的工具名称和输入 Schema。对于生产环境，应要求使用 JWT——请注意，API Key 无法保护该方法：

yaml x-google-api-management: mcp: tools-list: security: orderServiceJwt: [] # the object form also enables MCP globally

无论你是否保护工具发现，tools/call 始终会执行底层 REST 操作要求的身份验证。

4. 连接你的 Agent。 将任意 MCP 客户端指向网关的 /mcp 端点。在 ADK 中，这意味着配置工具集以及网关已要求的凭据：

python from google.adk.agents import Agent from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

order_tools = McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp", headers={"x-api-key": API_KEY}, ) )

agent = Agent( model="gemini-2.5-flash", name="order_support_agent", instruction="Help the user check on their orders.", tools=[order_tools], )

网关会将工具参数映射回操作对应的 REST 路径、查询参数、请求体和请求头，使请求经过现有策略，然后将后端响应作为 MCP 结果返回。若要查看实际传输内容：

shell curl -X POST "https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp"
-H "content-type: application/json"
-H "MCP-Protocol-Version: 2025-11-25"
-H "x-api-key: $API_KEY"
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}'

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text", "text":"{"orderId":"A-1042","status":"IN_TRANSIT","eta":"2026-09-24"}"}], "isError":false}}

为何通过网关提供 MCP 服务

• 可发现。 将网关连接到 API hub 后，其 MCP 服务器会连同 MCP 专属元数据一并发布到其中，并自动显示在 Agent Registry 中，方便 Agent 和开发者发现其提供的工具。
• 无需新增运维对象。 现有规范、网关、身份验证、配额和日志即可完成工作；由于 MCP 与 REST 流量共享一条策略路径，两者能够保持一致。

Public Preview 覆盖使用当前身份验证机制的 REST 和 OpenAPI 3.x 后端。MCP 资源与提示词、响应流式传输以及 Model Armor 载荷检查已在路线图中。有几项限制值得提前了解：返回空响应体的操作（如 HTTP 204）不会被暴露；深度嵌套的对象 Schema 可能无法在 tools/list 中完整渲染；单个网关最多可提供 1,000 个工具；MCP 与模型路由不能在同一个 API 配置中同时启用。有关当前支持范围，请参阅文档。

开始使用

MCP 支持现已在 Public Preview 中提供。请查看文档，立即将你的第一个 API 转换为可供 Agent 使用的工具。

Most enterprise capability sits behind REST APIs that agents cannot see. To make one callable by an agent today, teams typically stand up and operate a separate MCP server that re-implements the routing, authentication, and quota logic their gateway already handles. The Model Context Protocol (MCP) has become the standard way for agents to discover and invoke tools, and frameworks like the Agent Development Kit (ADK) and Gemini Enterprise speak it natively.

Google Cloud API Gateway now closes that gap. In Public Preview, API Gateway can act as a remote MCP server: annotate the OpenAPI spec you already deploy, deploy it, and your existing REST operations are available as agent-ready MCP tools — with no separate server to build, host, or maintain.

API Gateway is the lightweight on-ramp in Google Cloud's gateway lineup. If you have a service on Cloud Run and you want its API secured, managed, and exposed to agents in minutes, this is the fast path. For a full enterprise API and MCP platform — lifecycle management, advanced traffic policies, monetization — use Apigee. To govern what your agents call on the way out, including MCP servers like this one, use Agent Gateway. Model routing, which gives you one stable endpoint for outbound LLM calls, is the companion capability for the other direction of AI traffic.

How it works

API Gateway accepts standard MCP JSON-RPC requests on a single endpoint, transcodes each tools/call into the corresponding REST request, applies your existing policies, and translates the response back. Because the transcoded request is indistinguishable from a normal REST call, the JWT or API-key authentication, quota, and logging you already configured for that operation keep working unchanged — MCP and REST traffic share exactly one policy path, and a given operation draws on one quota allocation however it is invoked.

1. Annotate your OpenAPI spec. MCP requires OpenAPI 3.0.x or 3.1.x; OpenAPI 2.0 is not supported, so if your gateway still runs a 2.0 spec, migrate it first. Opt in at the document level with x-google-api-management.mcp, and customize or skip individual operations with x-google-mcp-tool. Each exposed operation needs a backend and a non-empty description.

openapi: 3.0.4
info:
  title: Order Service
  version: 1.0.0

x-google-api-management:
  mcp: true                 # expose this spec's operations as MCP tools
  backends:
    orders-backend:
      address: https://orders-a1b2c3-uc.a.run.app

paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-backend: orders-backend
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order.
          Use this when the user asks where an order is or when it will arrive."
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string

Plain text

A tool's description is the primary signal an LLM uses to decide when to call it, so write when and why to use the tool, not just what it returns.

2. Deploy the gateway. Deploy the API config as usual. API Gateway generates an MCP-aware configuration and begins serving MCP on the /mcp base path, with no extra infrastructure to provision.

3. Decide who can discover your tools. By default tools/list is unauthenticated, which is convenient for development but publishes your tool names and input schemas to anyone who asks. For production, require a JWT — note that API keys cannot secure this method:

x-google-api-management:
  mcp:
    tools-list:
      security:
        orderServiceJwt: []   # the object form also enables MCP globally

Plain text

tools/call always enforces whatever authentication the underlying REST operation requires, whether or not you secure discovery.

4. Connect your agent. Point any MCP client at the gateway's /mcp endpoint. In ADK, that is the toolset plus the credential your gateway already expects:

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

order_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp",
        headers={"x-api-key": API_KEY},
    )
)

agent = Agent(
    model="gemini-2.5-flash",
    name="order_support_agent",
    instruction="Help the user check on their orders.",
    tools=[order_tools],
)

Python

The gateway maps the tool's arguments back onto the REST path, query, body, and headers of your operation, runs the request through your existing policies, and returns the backend's response as an MCP result. To inspect that on the wire:

curl -X POST "https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp" \
  -H "content-type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}'

Shell

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text",
  "text":"{\"orderId\":\"A-1042\",\"status\":\"IN_TRANSIT\",\"eta\":\"2026-09-24\"}"}],
  "isError":false}}

JSON

Why serve MCP from the gateway

• Discoverable. Connect your gateway to API hub and its MCP server is published there with MCP-specific metadata and appears in Agent Registry automatically, so agents and developers can find the tools it exposes.
• Nothing new to operate. Your existing spec, gateway, authentication, quotas, and logging do the work — MCP and REST traffic stay consistent because they share one policy path.

The Public Preview covers REST and OpenAPI 3.x backends with your current authentication. MCP resources and prompts, response streaming, and Model Armor payload inspection are on the roadmap. A few limits are worth knowing up front: operations returning empty bodies such as HTTP 204 are not exposed, deeply nested object schemas may not render fully in tools/list, a gateway serves up to 1,000 tools, and MCP and model routing cannot be enabled in the same API config. See the documentation for the current scope.

Get started

MCP support is available now in Public Preview. Check out the documentation and turn your first API into an agent-ready tool today.