Depois que o Google colocou REST no API Gateway MCP, por que a descoberta ainda é JSON? OpenAPI 3.x até tools/list

Conclusão primeiro: o gateway vai fazer o papel de MCP Server. O contrato de descoberta continua sendo um documento JSON. Em 24 de setembro de 2026 o blog de desenvolvedores da Google disse que o Cloud API Gateway, em Public Preview, pode expor as operações OpenAPI 3.x que você já implanta como tools MCP remotos — sem um MCP Server extra para construir ou hospedar. A documentação chegou antes: as release notes de 11 de setembro já listam Enable MCP. O gateway aceita JSON-RPC padrão em /mcp, transcodifica tools/call no request REST existente e mantém JWT, API keys, cota e logs no mesmo caminho de política. O que o agent vê não é «REST virou mágica». São os nomes de tool e os input schemas do tools/list — ainda JSON.

Escrito em 30 de setembro de 2026, contra aquele post e a documentação do API Gateway ainda vigentes naquele dia. Este site já tem o que é MCP, por que a descoberta de Skill ainda é JSON e JSON malicioso e Tool Calling. Este texto só responde qual camada JSON você checa primeiro depois que o OpenAPI chega no gateway, e qual camada fica aberta por padrão.

O que de fato saiu em «gateway como MCP Server»

A linha oficial é curta: a maior parte da capacidade empresarial fica atrás de REST; agents não conseguem ver. Equipes costumam levantar um segundo MCP Server e reimplementar roteamento, auth e cota. API Gateway é a rampa leve da linha de gateways do Google Cloud. Um serviço Cloud Run que precisa ser gerenciado e exposto a agents em minutos vai por aqui. Ciclo de vida completo, política de tráfego pesada e monetização ficam no Apigee. Chamadas outbound do agent, inclusive MCP Servers como este, passam pelo Agent Gateway. O roteamento outbound de modelo é a outra direção, e não pode compartilhar um API config com o MCP.

Só quatro métodos de ciclo de vida são suportados: initialize, notifications/initialized, tools/list e tools/call. Todo o resto (resources/*, prompts/*) devolve JSON-RPC -32601. O transporte é HTTP POST. Não há stdio. O header de exemplo é MCP-Protocol-Version: 2025-11-25. A spec em si moveu o handshake em 2026-07-28; este preview trava em 2025-11-25. Até a string de versão é um campo que você alinha no envelope JSON primeiro.

Isto não é escrever outro MCP Server

O request REST transcodificado é indistinguível de uma chamada de browser ou SDK. A cota é por operação; MCP e REST compartilham a alocação. O backend não ganha uma segunda interface para agents. O que muda é a descoberta: as pessoas liam o OpenAPI; o modelo agora lê o JSON Schema dentro do tools/list.

Camada	Antes	Depois do Gateway MCP
Contrato humano	OpenAPI 2.0 / 3.x, muitas vezes YAML	Precisa subir para OpenAPI 3.0.x ou 3.1.x primeiro
Descoberta do agent	Um tools/list auto-hospedado	O gateway monta o tools/list a partir da mesma spec
Chamada	REST, ou o seu próprio tools/call	JSON-RPC tools/call → o REST original
Auth / cota	Política do gateway, às vezes escrita duas vezes	Continua sendo política do gateway; a descoberta tem um default separado

Então «nenhum MCP Server para operar» não é «nenhum contrato JSON para manter». Descriptions vazias, objetos profundos e resto de 2.0 aparecem na descoberta ou na transcodificação. Veja o que é MCP.

O contrato cresce a partir do OpenAPI 3.x

Ligue o MCP no documento com x-google-api-management.mcp. Por operação, x-google-mcp-tool pode renomear, reescrever a description ou pôr false para sair. Toda operação exposta precisa de um backend e de uma description não vazia. Só GET / POST / PUT / PATCH / DELETE entram. Nomes de tool precisam casar com [A-Za-z0-9_.-]{1,128} e ficar únicos no gateway.

A forma mínima oficial (YAML na página; o significado é um objeto JSON):

x-google-api-management:
  mcp: true
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order."
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string

A description é o sinal principal que o modelo usa para decidir quando chamar. A Google pede when / why, não só o que volta. Schemas de path, query, body e header viram arguments da tool. Objetos aninhados podem não renderizar por completo no tools/list — um limite documentado do preview, não um validador quebrado. Achate o OpenAPI no local, depois faça Diff contra o input schema do gateway.

tools/list não autentica por padrão

Por padrão qualquer um pode POST /mcp e receber o catálogo: nomes, descriptions, input schemas. Bom para desenvolvimento. Em produção isso publica o contrato de parâmetros. A Google recomenda um JWT no tools/list. No Public Preview uma API key não consegue proteger este método. A forma de objeto também liga o MCP no global; operações que você não quer expor precisam de x-google-mcp-tool: false.

x-google-api-management:
  mcp:
    tools-list:
      security:
        orderServiceJwt: []

tools/call sempre aplica o auth REST de baixo, com a descoberta trancada ou não. Um catálogo aberto e uma chamada trancada são duas coisas diferentes. Se nomes de tool e schemas são sensíveis, tranque o tools/list antes de publicar. É a mesma camada do guia de JSON malicioso: quanto mais largo o contrato que o modelo vê, mais larga a superfície de injeção.

tools/call continua sendo JSON-RPC

A forma no fio, na documentação, é:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}

O gateway mapeia arguments de volta para path / query / body / header, aplica a política e embrulha a resposta do backend como um result MCP. No debug, separe as camadas: o envelope de fora é JSON-RPC; o payload de dentro é JSON de negócio. Falhas de parse pertencem a uma camada ou à outra. O sample do ADK aponta Streamable HTTP para …/mcp e ainda pode mandar as credenciais que o gateway já espera.

Ligue o gateway ao API hub e um config com MCP ligado publica com metadados MCP e aparece no Agent Registry. O diretório mudou. O contrato de campos não: ainda é o schema crescido a partir do seu OpenAPI. A descoberta de Skill é outro documento JSON — veja SEP-2640 e skill://index.json. Não junte esses dois catálogos numa tabela só.

Limites para ler no Public Preview

OpenAPI 2.0 não é suportado. Suba para 3.x primeiro.
Operações com body vazio (HTTP 204) não são expostas como tools.
Schemas de objeto muito aninhados podem ser truncados no tools/list.
Um gateway serve até cerca de 1.000 tools.
MCP e model routing não podem compartilhar um API config.
Resources / prompts, streaming de resposta e inspeção do Model Armor ainda estão no roadmap.

Isso não é «polir depois». Uma operação 204 some do catálogo e o modelo vai chamar outra coisa. Um schema truncado não casa com um validador strict nem com o backend de verdade. O guia de migração MCP 2026 é sobre versões de protocolo. Este artigo acrescenta: a list que o gateway gera pode não ser igual ao OpenAPI completo do seu repo.

Quatro documentos JSON para checar antes de ligar o switch

O OpenAPI 3.x no repo. Suba o 2.0 primeiro. Toda operação exposta tem description não vazia, um backend e um nome de tool legal.
O tools/list do gateway. Cheque se input schemas foram truncados e se operações a mais vazararam.
Um tools/call de verdade. Os arguments mapeiam de volta para REST? O envelope é JSON-RPC 2.0?
O objeto de segurança da descoberta. Não publique com o tools/list ainda aberto. O nome do scheme JWT precisa já existir em components.securitySchemes.

Inspecione a spec com ferramentas JSON locais

Antes de ligar o MCP, abra três textos no navegador: o OpenAPI (converta YAML para JSON primeiro), uma resposta de tools/list e o objeto arguments que você vai mandar no tools/call.

Validador JSON — a gramática é legal; se você tem schema, cheque campos required e chaves a mais juntos.
JSON ↔ YAML — a maior parte do OpenAPI mora em YAML; converta antes de fazer Diff contra a list.
JSON Diff — compare o schema de parameters no repo com o inputSchema que o gateway devolveu.

Nada sai do navegador. Achate o contrato, depois ligue o switch do gateway. O gateway vai transcodificar. Seus nomes de campo e a lista required não deveriam afrouxar junto com o truncamento do preview.

FAQ

Isto é GA? Eu ainda preciso do meu próprio MCP Server?

Em 30 de setembro de 2026 é Public Preview. REST mais OpenAPI 3.x e os quatro métodos de ciclo de vida podem ficar no gateway. Resources, prompts, streaming, stdio ou mais de cerca de 1.000 tools ainda precisam do seu próprio server.

Se o tools/list está aberto, a API key não protege as chamadas?

Chamadas seguem a política REST. O catálogo publica nomes e input schemas por padrão. Uma API key não protege o tools/list. Tranque a descoberta com um JWT em produção.

Minha spec ainda é OpenAPI 2.0 / Swagger. Consigo ligar isto?

Não. Suba para 3.0.x ou 3.1.x, depois adicione a extensão mcp.

Isto é a mesma coisa que a descoberta de Skill do SEP-2640 em setembro?

Não. A descoberta de Skill é skill://index.json ou skills/list. O caminho do gateway transforma operações REST em tools/list. Dois documentos JSON, dois conjuntos de campos.

Por que o schema do tools/list é mais raso que o meu OpenAPI?

O preview diz que objetos profundos podem não renderizar por completo. Confie na resposta do gateway. Faça Diff contra a spec do repo e veja quais campos required sumiram.

Para onde foi o meu DELETE que devolve 204?

Operações com body vazio não são expostas como tools. O modelo não vai ver esse nome e não vai chamar.

Resumo

O API Gateway tira o processo de MCP Server. Não tira o contrato JSON. O OpenAPI 3.x cresce o tools/list. tools/call continua JSON-RPC. A política continua sendo a política REST que você já tem. Um catálogo aberto, um schema aninhado truncado e uma operação 204 que some são checagens antes do lançamento — não «preview ligado, pronto».

Achate o OpenAPI, a resposta da list e uma amostra de call no local, depois ponha mcp: true. O gateway vai transcodificar. O contrato de campos não deveria afrouxar junto com os limites do preview.