Descripción general del Protocolo de contexto del modelo

En este documento, se proporciona una descripción general de la compatibilidad con el Protocolo de contexto del modelo (MCP) en API Gateway.

API Gateway puede actuar como un servidor MCP remoto, lo que te permite exponer tus APIs de REST existentes a los agentes de IA y los LLM sin tener que volver a escribir tus servicios de backend.

Fondo

El Protocolo de contexto del modelo (MCP) es un estándar abierto que te permite compilar agentes de IA directamente en tu infraestructura existente. En lugar de escribir código de integración personalizado para cada herramienta o API, el MCP proporciona una forma estándar para que los modelos de IA descubran e invoquen la funcionalidad en tu entorno.

Cuando se configura como servidor de MCP, API Gateway actúa como proxy. Traduce los mensajes estándar del protocolo JSON-RPC de MCP que se envían desde los sistemas basados en agentes a solicitudes REST HTTP estándar hacia tus back-ends existentes.

Funciones admitidas

Durante la versión preliminar pública, API Gateway admite las siguientes funciones de MCP:

  • Servidor de MCP remoto: API Gateway actúa como un servidor remoto y recibe solicitudes de MCP a través de HTTP (POST).
  • Integración de OpenAPI 3.x: La configuración de MCP se deriva directamente de tu especificación de OpenAPI 3.x con extensiones personalizadas.
  • Métodos de ciclo de vida de MCP compatibles:
    • initialize: Establece la versión y las capacidades del protocolo.
    • notifications/initialized: Confirma el handshake.
    • tools/list: Permite que los clientes descubran las herramientas disponibles y sus esquemas.
    • tools/call: Permite que los clientes invoquen una herramienta con argumentos.

Limitaciones

Se aplican las siguientes limitaciones a la compatibilidad con MCP en API Gateway:

  • No se admiten los recursos (resources/*) ni las instrucciones (prompts/*).
  • No se admite el transporte de Stdio.
  • No se admite OpenAPI 2.0.
  • No se admiten las llamadas a herramientas de transmisión ni las de ejecución prolongada.
  • Exclusión mutua del enrutamiento del modelo: No puedes habilitar MCP y el enrutamiento del modelo en la misma configuración de la API. Si x-google-api-management.mcp está habilitado, no se puede usar x-google-model-router.

Para obtener una lista completa de los límites técnicos, consulta Limitaciones de las características de OpenAPI 3.x.

Casos de uso

  • Expón las APIs de REST existentes como herramientas de MCP: Convierte tus APIs existentes en herramientas listas para la IA sin cambiar el código de backend.
  • Seleccionar herramientas por operación: Elige de forma explícita qué rutas y métodos de la API se exponen a los agentes.
  • Protege la superficie de la herramienta: Aplica las políticas de seguridad existentes de API Gateway (como las claves de API o OAuth) a tu endpoint de MCP.

Flujo de solicitud

La ruta canónica para las solicitudes de MCP es <basepath>/mcp, donde <basepath> se deriva de la URL de tu puerta de enlace o de la configuración de x-google-endpoint.

En el siguiente diagrama, se muestra el flujo de solicitudes para una solicitud de MCP tools/call:

  1. Un cliente de MCP (p.ej., un agente de IA) envía una solicitud de JSON-RPC al extremo de MCP de la puerta de enlace (p.ej., POST /mcp o POST /v1/mcp si se usa un prefijo de versión).
  2. La puerta de enlace valida la solicitud y verifica la autenticación.
  3. La puerta de enlace inspecciona la carga útil para determinar a qué herramienta se llama.
  4. La puerta de enlace traduce la carga útil de MCP en una solicitud HTTP estándar (ruta, parámetros, cuerpo) según la asignación definida en la configuración de la API.
  5. La puerta de enlace reenvía la solicitud al servicio de backend.
  6. El backend devuelve una respuesta HTTP estándar.
  7. La puerta de enlace traduce la respuesta HTTP a una respuesta JSON-RPC de MCP y la devuelve al cliente.

Descubrimiento a través del centro de APIs y el Agent Registry

Si integras tu puerta de enlace con el Centro de APIs, esta se publicará en el Centro de APIs como un servidor de MCP con metadatos adicionales específicos de MCP y también aparecerá automáticamente en Agent Registry.

Para las puertas de enlace sin MCP habilitado, se publican metadatos de API estándar. Solo las puertas de enlace que tengan habilitado el MCP mostrarán estas configuraciones adicionales del MCP en el centro de APIs.

No se necesita un paso de registro por separado. Luego, los agentes pueden descubrir el servidor y sus herramientas a través de cualquiera de los catálogos.

Para consultar Agent Registry, habilita su API en tu proyecto:

gcloud services enable agentregistry.googleapis.com

¿Qué sigue?