API Gateway do Google Cloud transforma specs REST em ferramentas MCP

Toda equipe que já tentou plugar um agente numa API interna conhece o problema: a lógica de roteamento, autenticação e quota já existe no gateway, mas para o agente enxergar aquilo como uma ferramenta MCP↳MCP7 conteúdosArquitetura de Sistemas Cognitivos: Integração de RAG, MCP e LLMs no Ecossistema .NETDev (Back & Front) · abr 2026MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025Agentes de IA com LLMs de Código Aberto: Integração Prática com o Model Context Protocol (MCP)AI · ago 2025Ver tudo em AI →, alguém precisa reimplementar tudo de novo num servidor MCP dedicado. Foi esse trabalho duplicado que o Google Cloud↳Google Cloud13 conteúdosPrograma da Google Cloud no Brasil projeta formar de forma gratuita 30 mil universitáriosDev (Back & Front) · mar 2026Google Cloud OnBoard capacita estudantes e desenvolvedores de TIGestão Dev & TI · mai 2019Desenvolvedores poderão participar de treinamento gratuito do Google CloudGestão Dev & TI · mai 2019Ver tudo em DevSecOps → atacou no anúncio de 24 de setembro de 2026: o API Gateway agora funciona como um servidor MCP remoto, em Public Preview, transcodificando chamadas tools/call em requisições REST comuns contra o spec OpenAPI que você já publica.

Vale separar isso do resto do portfólio de gateway do Google, porque a escolha errada custa caro depois. O API Gateway é a porta de entrada leve: se você tem um serviço no Cloud Run e quer expô-lo com segurança em minutos, é o caminho rápido. Para gerenciamento de ciclo de vida completo, políticas de tráfego avançadas e monetização, o produto é o Apigee. Para controlar o que seus próprios agentes chamam para fora — inclusive outros servidores MCP como este — entra o Agent Gateway. E se o que você precisa é um endpoint estável para chamadas de LLM de saída, isso é Model Routing, que inclusive não pode ser habilitado na mesma config de API que o MCP.

Como a transcodificação funciona por baixo do capô

O gateway aceita requisições JSON-RPC padrão do MCP num único endpoint, transforma cada tools/call na requisição REST correspondente, aplica as políticas que você já tinha configurado para aquela operação e traduz a resposta de volta para o formato MCP. Como a requisição transcodificada é indistinguível de uma chamada REST normal, o JWT ou API key, a quota e o log que você já tinha para aquela operação continuam funcionando sem alteração. MCP e REST compartilham exatamente o mesmo caminho de política, e uma operação consome a mesma alocação de quota não importa por qual via ela foi chamada.

Anotando o OpenAPI: o primeiro passo real

O requisito de entrada é que o spec esteja em OpenAPI 3.0.x ou 3.1.x — 2.0 não é suportado, então se o seu gateway ainda roda um spec antigo, a migração vem antes de qualquer coisa. Você opta pelo MCP no nível do documento com x-google-api-management.mcp: true e customiza (ou pula) operações específicas com x-google-mcp-tool. Toda operação exposta precisa de um backend↳Back-end49 conteúdosIntegração front-end com backend: 7 decisões que evitam caos entre APIs, BFF e GraphQLDev (Back & Front) · abr 2026Como criar uma FAKE API REST para testes — JSONPlaceholderDev (Back & Front) · set 2025Construindo um aplicativo de bate-papo de IA simples com Spring AI e AngularDev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → e de uma descrição não vazia:

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

x-google-api-management:
  mcp: true

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

O detalhe que faz diferença na prática: a descrição do x-google-mcp-tool é o principal sinal que o LLM usa para decidir quando chamar a ferramenta. Escrever "retorna o status do pedido" é bem mais fraco do que explicar quando e por que usá-la, como no exemplo acima. Isso é engenharia de prompt disfarçada de documentação de API, e vale o tempo extra de revisão.

Deploy, segurança de descoberta e o tropeço mais comum

O deploy é o de sempre — você sobe a config de API normalmente e o gateway já gera a configuração ciente de MCP, servindo no path base /mcp, sem infraestrutura extra para provisionar. O ponto que eu destacaria como o tropeço mais provável de quem for adotar isso é a segurança do tools/list: por padrão, listar as ferramentas disponíveis é uma chamada sem autenticação, o que é conveniente em desenvolvimento mas publica nomes de ferramentas e schemas de entrada para qualquer um que perguntar. Em produção isso precisa de JWT — e API keys não servem para proteger esse método específico:

mcp:
  tools-list:
    security:
      orderServiceJwt: []

Já o tools/call sempre aplica a autenticação que a operação REST subjacente exige, independentemente de você proteger ou não a descoberta. Ou seja: esquecer de travar o tools-list não te expõe a chamadas indevidas, mas expõe seu catálogo de ferramentas a qualquer olhar curioso — o que já é informação demais em muitos contextos corporativos.

Conectando um agente e inspecionando o tráfego

Para quem usa o Agent Development Kit, o encaixe é direto: um McpToolset apontando para o endpoint /mcp do gateway, com o header de credencial que o gateway já espera.

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],
)

Se eu estivesse validando essa integração antes de confiar nela, o primeiro teste seria bater direto no endpoint com curl, sem passar pelo agente, só para confirmar que o transcoding está saindo como esperado:

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"}}}'

A resposta documentada pelo Google mostra o formato de retorno esperado, com o corpo da API original embutido como texto dentro do envelope MCP:

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

Se o retorno vier vazio ou com erro de schema, o roteiro de depuração óbvio é conferir se a operação tem descrição não vazia e backend declarado — os dois requisitos que o Google lista como obrigatórios para uma operação virar ferramenta MCP.

O que ainda não funciona e o que muda pra quem já usa Apigee

A Public Preview cobre backends REST e OpenAPI 3.x com a autenticação que você já tem configurada. Recursos e prompts MCP, streaming de resposta e inspeção de payload via Model Armor estão no roteiro, não disponíveis ainda. Há limites que valem anotar antes de arquitetar em cima disso: operações que retornam corpo vazio, como HTTP 204, simplesmente não são expostas como ferramenta; schemas de objeto muito aninhados podem não renderizar corretamente no tools/list; um gateway serve no máximo 1.000 ferramentas; e MCP e Model Routing não podem conviver na mesma config de API.

Para quem já opera Apigee, a pergunta natural é se isso substitui a plataforma. Não substitui — o próprio anúncio do Google é explícito em posicionar API Gateway como o "on-ramp" leve e deixar o ciclo de vida completo de API para o Apigee. O ganho real aqui é para quem tem uma API simples rodando no Cloud Run ou GKE e quer, sem subir peça nova de infraestrutura, deixá-la discoverable por um agente Gemini Enterprise ou por qualquer cliente MCP compatível com Streamable HTTP. Se sua API já vive dentro do Apigee, o caminho de integração com agentes passa por outro produto da mesma família, não por este.

Fonte: Google Developers Blog