Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Configura el Protocolo de contexto del modelo

En este documento, se describe cómo configurar API Gateway para que actúe como un servidor remoto del Protocolo de contexto del modelo (MCP).

Antes de comenzar

Asegúrate de tener una especificación de OpenAPI 3.x válida para tu API. MCP no es compatible con OpenAPI 2.0.
Asegúrate de comprender los conceptos básicos de API Gateway.

Validación de la configuración

Cuando subes tu especificación de OpenAPI, API Gateway realiza las siguientes validaciones para la configuración de MCP:

Ubicación: La extensión x-google-mcp-tool solo se debe especificar a nivel de la operación individual.
Método HTTP: Solo las operaciones GET, POST, PUT, PATCH y DELETE se pueden exponer como herramientas de MCP.
Nombre de la herramienta: Los nombres de las herramientas deben coincidir con [A-Za-z0-9_.-]{1,128} y ser únicos en toda la especificación.
Descripción: Cada herramienta debe resolverse en una descripción no vacía (tomada de la descripción, el resumen o la anulación de la operación). Se rechazan las operaciones sin una descripción que se pueda resolver.
Seguridad: Si configuras la autenticación para tools/list, debes nombrar exactamente un esquema de seguridad JWT definido en components.securitySchemes. La seguridad de las claves de API no es compatible con tools/list en la versión preliminar pública.

Modelo de autenticación

API Gateway aplica diferentes reglas de autenticación según el método de MCP al que se llame:

Ciclo de vida del protocolo: Los métodos initialize y notifications/initialized son no autenticados.
Tool Invocation (tools/call): Reutiliza las políticas de autenticación definidas para la operación subyacente en tu especificación de OpenAPI. Exige los mismos requisitos de clave de API o JWT que si se llamara al extremo de REST directamente.
Descubrimiento de herramientas (tools/list): De forma predeterminada, este método no está autenticado. Sin embargo, como práctica recomendada de seguridad, se recomienda proteger el descubrimiento de herramientas habilitando la autenticación para este método con tools-list.security. Si decides habilitar la autenticación, debes usar un esquema de seguridad JWT. La autenticación con clave de API no es compatible con tools/list.

Pasos para configurar el MCP

Sigue estos pasos para exponer tu API como herramientas de MCP:

1. Identifica las operaciones que se expondrán

Revisa tu especificación de OpenAPI y decide qué operaciones deberían estar disponibles para los agentes de IA.

2. Actualiza tu especificación de OpenAPI

Puedes habilitar el MCP de forma global para todas las operaciones aptas o configurarlo por operación.

Habilitación global

Para habilitar el MCP de forma global, agrega el campo mcp a x-google-api-management a nivel del documento:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Cuando se habilita de forma global, todas las operaciones aptas (según el método y la ruta de HTTP) se exponen como herramientas de MCP. De forma predeterminada, el nombre de la herramienta es el operationId de la operación, y la descripción es la descripción o el resumen de la operación.

Configuración por operación

Puedes anular la configuración global o exponer operaciones de forma selectiva con x-google-mcp-tool:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

También puedes inhabilitar una operación cuando se habilita de forma global configurando x-google-mcp-tool: false.

3. Autenticar `tools/list` (recomendado)

De forma predeterminada, el método tools/list (que enumera las herramientas disponibles) no está autenticado. Como práctica recomendada de seguridad, se recomienda aplicar la autenticación configurando tools-list.security en x-google-api-management/mcp. Debes usar un esquema JWT, ya que las claves de API no son compatibles con este método.

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

4. Crea e implementa la configuración de API

Crea una configuración de API a partir de tu especificación anotada y, luego, impleméntala en una puerta de enlace con el flujo estándar. Consulta Implementar una API en una puerta de enlace para obtener más detalles.

5. Verifica la compatibilidad con MCP

Una vez implementada, puedes verificar que la puerta de enlace esté entregando solicitudes de MCP.

Apretón de manos

Envía una solicitud de inicialización para establecer la versión y las capacidades del protocolo:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Confirmación de conexión

Confirma la inicialización. La puerta de enlace responde con HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Descubre herramientas

Enumera las herramientas disponibles:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Cómo se asignan los argumentos a la solicitud de REST

Los argumentos que se pasan a una herramienta se asignan a la solicitud de REST subyacente según la especificación de OpenAPI:

Parámetros de ruta y de consulta: Se convierten en propiedades de nivel superior en el objeto arguments, con claves según sus nombres de parámetros de OpenAPI.
Cuerpo de la solicitud: Anidado en una sola propiedad llamada body. Por ejemplo, para crear un recurso, debes pasar {"body": {"fieldName": "value"}}.
Encabezados: También se convierten en propiedades de nivel superior. La puerta de enlace los inyecta como encabezados HTTP estándar en la llamada de backend.

La solicitud de backend transcodificada no se distingue de una solicitud REST directa a tu servicio de backend. Los servicios de backend no pueden distinguir de forma programática entre una llamada directa a la API de REST y una transcodificada desde MCP.

Invoca una herramienta

Invocar una herramienta específica Asegúrate de incluir los tokens de autenticación necesarios si la operación de REST subyacente los requiere:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Observabilidad

Las solicitudes de MCP generan registros y métricas estándar de API Gateway. Puedes distinguir el tráfico de MCP del tráfico REST estándar inspeccionando la ruta de la solicitud (que suele terminar en /mcp) o configurando métricas personalizadas.

Soluciona problemas de fallas de MCP

La MCP distingue entre las fallas de transporte y las fallas de protocolo. La puerta de enlace devuelve HTTP 200 con un objeto de error JSON-RPC para errores de protocolo y aplicación, ya que las respuestas que no son 200 pueden provocar que muchos clientes de MCP fallen en la capa de transporte.

En la siguiente tabla, se describen los síntomas y las soluciones comunes:

Síntoma	Código de JSON-RPC	Estado de HTTP	Significado y solución típica
No se permite el método	No disponible	`405`	Se envió una solicitud que no es POST a `/mcp`. Solo se admite el `POST` HTTP.
Error de análisis de JSON	`-32700`	`400`	El cuerpo de la solicitud no es un JSON válido.
Falta el método o el ID, o no son válidos	`-32600`	`200`	El cuerpo es un JSON válido, pero no una solicitud JSON-RPC válida. Verifica los campos obligatorios (`jsonrpc`, `method`, `id`).
No se admite el método	`-32601`	`200`	El método está fuera del alcance admitido (p.ej., `ping`).
Versión del protocolo no compatible	`-32602`	`200`	`protocolVersion` nombra una versión que la puerta de enlace no admite.
Falta la versión del protocolo	`-32602`	`200`	Los parámetros de `initialize` omiten `protocolVersion` o no es una cadena.
Herramienta desconocida	`-32602`	`200`	No se encontró el nombre de la herramienta. Borra la caché del cliente o verifica la implementación.
Argumentos de la herramienta no válidos	`-32602`	`200`	Faltan argumentos o no son válidos. Verifica el anidamiento de la clave `body`.
El cuerpo es demasiado grande	`-32000`	`200`	La carga útil de la respuesta superó los límites de tamaño.
El cuerpo del transporte es demasiado grande	No disponible	`413`	El cuerpo de la solicitud HTTP sin procesar superó los límites de transporte de la puerta de enlace.
Error del servidor	`-32000`	`200`	No se puede analizar la respuesta del backend. Verifica los registros.
Sin autorización o prohibido	No disponible	`401`/`403`	Fallo en la autenticación La respuesta incluye un encabezado `WWW-Authenticate` que apunta a los metadatos del recurso protegido.

Por lo general, los errores de la aplicación de backend se muestran como una respuesta JSON-RPC exitosa (HTTP 200) con result.isError: true que contiene el cuerpo del error de backend.