Después de que Google ponga REST en API Gateway MCP, ¿por qué el descubrimiento sigue siendo JSON? OpenAPI 3.x hasta tools/list

De entrada: el gateway hará de MCP server. El contrato de descubrimiento sigue siendo un documento JSON. El 24 de septiembre de 2026 el blog de desarrolladores de Google dijo que Cloud API Gateway, en Public Preview, puede exponer las operaciones OpenAPI 3.x que ya despliegas como herramientas MCP remotas — sin un MCP server extra que construir o alojar. La documentación llegó antes: las release notes del 11 de septiembre ya listan Enable MCP. El gateway acepta JSON-RPC estándar en /mcp, transcodifica tools/call a la petición REST existente y mantiene JWT, API keys, cuota y logs en un solo camino de política. Lo que el agente ve no es «REST se volvió magia». Son los nombres de herramienta y los input schemas de tools/list — sigue siendo JSON.

Escrito a fecha de 30 de septiembre de 2026, contra esa entrada del blog y la documentación de API Gateway aún vigente ese día. Este sitio ya tiene qué es MCP, por qué el descubrimiento de Skill sigue siendo JSON y JSON malicioso y Tool Calling. Este texto solo responde qué capa JSON compruebas primero cuando OpenAPI aterriza en el gateway, y qué capa queda abierta por defecto.

Qué se publicó de verdad con «gateway as MCP server»

La línea oficial es corta: la mayor parte de la capacidad empresarial está detrás de REST; los agentes no la ven. Los equipos suelen levantar un segundo MCP server y reimplementar routing, auth y cuota. API Gateway es la rampa ligera de la línea de gateways de Google Cloud. Un servicio de Cloud Run que hay que gestionar y exponer a agentes en minutos entra aquí. El ciclo de vida completo, las políticas de tráfico pesado y la monetización se quedan en Apigee. Las llamadas de agente salientes, incluidos MCP servers como este, pasan por Agent Gateway. El model routing saliente es la otra dirección, y no puede compartir una API config con MCP.

Solo se soportan cuatro métodos de ciclo de vida: initialize, notifications/initialized, tools/list y tools/call. Todo lo demás (resources/*, prompts/*) devuelve JSON-RPC -32601. El transporte es HTTP POST. No hay stdio. La cabecera de ejemplo es MCP-Protocol-Version: 2025-11-25. La spec misma movió el handshake el 2026-07-28; esta preview clava 2025-11-25. Hasta el string de versión es un campo que alineas primero en el sobre JSON.

Esto no es escribir otro MCP server

La petición REST transcodificada es indistinguible de una llamada de navegador o SDK. La cuota es por operación; MCP y REST comparten la asignación. El backend no crece una segunda interfaz para agentes. Lo que cambia es el descubrimiento: la gente leía OpenAPI; el modelo ahora lee el JSON Schema dentro de tools/list.

Capa	Antes	Tras Gateway MCP
Contrato humano	OpenAPI 2.0 / 3.x, a menudo YAML	Primero hay que pasar a OpenAPI 3.0.x o 3.1.x
Descubrimiento del agente	Un tools/list autoalojado	El gateway construye tools/list a partir de la misma spec
Llamada	REST, o tu propio tools/call	JSON-RPC tools/call → el REST original
Auth / cuota	Política del gateway, a veces escrita dos veces	Sigue siendo política del gateway; el descubrimiento tiene un default aparte

Así que «ningún MCP server que operar» no es «ningún contrato JSON que mantener». Las descripciones vacías, los objetos profundos y el 2.0 residual aparecen en el descubrimiento o en la transcodificación. Ver qué es MCP.

El contrato crece a partir de OpenAPI 3.x

Activa MCP a nivel de documento con x-google-api-management.mcp. Por operación, x-google-mcp-tool puede renombrar, reescribir la descripción o poner false para excluirse. Cada operación expuesta necesita un backend y una descripción no vacía. Solo califican GET / POST / PUT / PATCH / DELETE. Los nombres de herramienta deben coincidir con [A-Za-z0-9_.-]{1,128} y ser únicos en el gateway.

La forma mínima oficial (YAML en la página; el significado es un 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

La descripción es la señal principal que el modelo usa para decidir cuándo llamar. Google pide when / why, no solo qué vuelve. Los schemas de path, query, body y header se convierten en arguments de la herramienta. Los objetos anidados pueden no renderizarse por completo en tools/list — un límite documentado de la preview, no un validador roto. Aplana el OpenAPI en local y luego haz Diff contra el input schema del gateway.

tools/list no autentica por defecto

Por defecto cualquiera puede hacer POST /mcp y recibir el catálogo: nombres, descripciones, input schemas. Bien para desarrollo. En producción publica el contrato de parámetros. Google recomienda un JWT en tools/list. En Public Preview una API key no puede proteger este método. La forma objeto también activa MCP de forma global; las operaciones que no quieras exponer necesitan x-google-mcp-tool: false.

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

tools/call siempre aplica la auth REST subyacente, da igual que el descubrimiento esté cerrado o no. Un catálogo abierto y una llamada cerrada son dos cosas distintas. Si los nombres de herramienta y los schemas son sensibles, cierra tools/list antes de publicar. Es la misma capa que la guía de JSON malicioso: cuanto más ancho el contrato que ve el modelo, más ancha la superficie de inyección.

tools/call sigue siendo JSON-RPC

La forma en el cable de la documentación es:

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

El gateway mapea arguments de vuelta a path / query / body / header, aplica la política y envuelve la respuesta del backend como un result MCP. Al depurar, separa las capas: el sobre exterior es JSON-RPC; el payload interior es JSON de negocio. Los fallos de parse pertenecen a una capa o a la otra. El ejemplo de ADK apunta Streamable HTTP a …/mcp y puede seguir enviando las credenciales que el gateway ya espera.

Engancha el gateway a API hub y una config con MCP se publica con metadatos MCP y aparece en Agent Registry. El directorio cambió. El contrato de campos no: sigue siendo el schema que creció a partir de tu OpenAPI. El descubrimiento de Skill es otro documento JSON — ver SEP-2640 y skill://index.json. No fusiones esos dos catálogos en una sola tabla.

Límites que hay que leer en Public Preview

OpenAPI 2.0 no se soporta. Primero actualiza a 3.x.
Las operaciones con cuerpo vacío (HTTP 204) no se exponen como herramientas.
Los schemas de objetos muy anidados pueden truncarse en tools/list.
Un gateway sirve hasta unos 1.000 tools.
MCP y model routing no pueden compartir una misma API config.
Resources / prompts, el streaming de respuestas y la inspección de Model Armor siguen en el roadmap.

Esto no es «ya lo puliremos». Una operación 204 desaparece del catálogo y el modelo llamará a otra cosa. Un schema truncado no coincidirá con un validador strict ni con el backend real. La guía de migración MCP 2026 trata de versiones de protocolo. Este artículo añade: la list que genera el gateway puede no igualar el OpenAPI completo de tu repo.

Cuatro documentos JSON que comprobar antes de activar el interruptor

El OpenAPI 3.x del repo. Primero actualiza el 2.0. Cada operación expuesta tiene una descripción no vacía, un backend y un nombre de tool legal.
El tools/list del gateway. Comprueba si los input schemas se truncaron y si se filtraron operaciones extra.
Un tools/call real. ¿Los arguments mapean de vuelta a REST? ¿El sobre es JSON-RPC 2.0?
El objeto de seguridad del descubrimiento. No publiques con tools/list aún abierto. El nombre del scheme JWT tiene que existir ya en components.securitySchemes.

Inspecciona la spec con herramientas JSON locales

Antes de activar MCP, extiende tres textos en el navegador: el OpenAPI (convierte YAML a JSON primero), una respuesta de tools/list y el objeto arguments que enviarás a tools/call.

Validador JSON — ¿es legal la gramática?; si tienes un schema, comprueba juntos los campos required y las claves extra.
JSON ↔ YAML — la mayoría del OpenAPI vive como YAML; conviértelo antes de hacer Diff contra la list.
JSON Diff — compara el schema de parameters del repo con el inputSchema que devolvió el gateway.

Nada sale del navegador. Aplana el contrato y luego activa el interruptor del gateway. El gateway transcodificará. Tus nombres de campo y la lista required no deberían aflojarse con el truncado de la preview.

FAQ

¿Esto es GA? ¿Sigo necesitando mi propio MCP server?

A fecha de 30 de septiembre de 2026 es Public Preview. REST más OpenAPI 3.x y los cuatro métodos de ciclo de vida pueden sentarse en el gateway. Resources, prompts, streaming, stdio o más de unos 1.000 tools siguen necesitando tu propio server.

Si tools/list está abierto, ¿la API key no protege igual las llamadas?

Las llamadas siguen la política REST. El catálogo publica nombres e input schemas por defecto. Una API key no puede proteger tools/list. Cierra el descubrimiento con un JWT en producción.

Mi spec sigue siendo OpenAPI 2.0 / Swagger. ¿Puedo activar esto?

No. Actualiza a 3.0.x o 3.1.x y luego añade la extensión mcp.

¿Es lo mismo que el descubrimiento de Skill de SEP-2640 en septiembre?

No. El descubrimiento de Skill es skill://index.json o skills/list. El camino del gateway convierte operaciones REST en tools/list. Dos documentos JSON, dos conjuntos de campos.

¿Por qué el schema de tools/list es más superficial que mi OpenAPI?

La preview dice que los objetos profundos pueden no renderizarse por completo. Confía en la respuesta del gateway. Haz Diff contra la spec del repo y mira qué campos required cayeron.

¿Dónde se fue mi DELETE que devuelve 204?

Las operaciones con cuerpo vacío no se exponen como herramientas. El modelo no verá ese nombre y no lo llamará.

Resumen

API Gateway se lleva el proceso MCP server. No se lleva el contrato JSON. OpenAPI 3.x hace crecer tools/list. tools/call sigue siendo JSON-RPC. La política sigue siendo la política REST que ya tienes. Un catálogo abierto, un schema anidado truncado y una operación 204 que desaparece son comprobaciones antes del lanzamiento — no «preview activada, listo».

Aplana el OpenAPI, la respuesta de list y una muestra de call en local, y luego pon mcp: true. El gateway transcodificará. El contrato de campos no debería aflojarse con los límites de la preview.