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 de 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 definido en components.securitySchemes. El esquema puede ser un esquema de JWT o un esquema de clave de API. Si usas un esquema de JWT, también debes nombrarlo en el requisito security de nivel superior de la especificación.

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 no están autenticados.
Invocación de herramientas (tools/call): Reutiliza las políticas de autenticación definidas para la operación subyacente en tu especificación de OpenAPI. Aplica los mismos requisitos de clave de API o JWT que cuando se llama directamente al extremo de REST.
Detección de herramientas (tools/list): De forma predeterminada, este método no está autenticado. Sin embargo, como práctica recomendada de seguridad, te recomendamos que protejas el descubrimiento de herramientas habilitando la autenticación para este método con tools-list.security. Puedes autenticar tools/list con un JWT o una clave de API.

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 deben estar disponibles para los agentes de IA.

2. Actualiza tu especificación de OpenAPI

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

Habilitación global

Habilita MCP de forma global agregando 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 acceso 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. Autentica `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, te recomendamos que apliques la autenticación configurando tools-list.security en x-google-api-management.mcp. Puedes nombrar un esquema de JWT o un esquema de clave de API.

En el siguiente ejemplo, se requiere un JWT:

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

En el siguiente ejemplo, se requiere una clave de API. Los clientes deben enviar la clave en el encabezado HTTP x-api-key; tools/list no lee las claves de API de los parámetros de consulta. Una solicitud sin una clave válida recibe un error de JSON-RPC y no se muestra la lista de herramientas. Para aprender a crear una clave de API, consulta Usa claves de API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. Crea e implementa la configuración de la 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 Implementa una API en una puerta de enlace para obtener más detalles. Para cambiar las herramientas más adelante, consulta Actualiza las herramientas de MCP expuestas.

5. Verifica la compatibilidad con MCP

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

Handshake

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

Confirmar el protocolo de enlace

Reconoce 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. Si configuraste tools-list.security, agrega la credencial coincidente, como un encabezado Authorization: Bearer para un JWT o un encabezado x-api-key para una clave de API:

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 de acceso y de consulta: Se convierten en propiedades de nivel superior en el objeto arguments, con clave por sus nombres de parámetros de OpenAPI.
Cuerpo de la solicitud: Se anida 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 inserta como encabezados HTTP estándar en la llamada al backend.

La solicitud de backend transcodificada no se puede distinguir de una solicitud de REST directa a tu servicio de backend. Los servicios de backend no pueden distinguir de forma programática entre una llamada de REST directa y una transcodificada desde el 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"}
  }
}'

Actualiza las herramientas de MCP expuestas

Las configuraciones de API en API Gateway son inmutables, por lo que no puedes cambiar la definición de la API en una configuración de API existente. Como resultado, la respuesta tools/list es estática para cada configuración de API implementada.

Para agregar, quitar, cambiar el nombre o actualizar las herramientas de MCP expuestas o la configuración de seguridad de tools/list, crea una nueva configuración de API y, luego, impleméntala en tu puerta de enlace:

Actualiza tu especificación de OpenAPI 3.x, incluidas las operaciones, los valores de operationId, los resúmenes, los parámetros y las extensiones x-google-api-management.mcp y x-google-mcp-tool.
Crea una configuración de API nueva con un ID de configuración de API nuevo:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Reemplaza lo siguiente:
- NEW_CONFIG_ID: Es un ID nuevo para la configuración de la API actualizada.
- API_ID: Es el ID de la API de API Gateway.
- API_DEFINITION: Es la ruta de acceso a tu especificación de OpenAPI 3.x actualizada.
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
- SERVICE_ACCOUNT_EMAIL: Es la dirección de correo electrónico de la cuenta de servicio que se usa para firmar tokens para backends con autenticación configurada. Omite esta marca si ninguno de tus backends requiere autenticación.
Para obtener más información, consulta Crea una configuración de API.
Actualiza cada puerta de enlace que entrega la API para usar la nueva configuración de API:
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
Reemplaza lo siguiente:
- GATEWAY_ID: Es el ID de la puerta de enlace que se actualizará.
- GCP_REGION: la región en la que se implementa la puerta de enlace
Para obtener más información, consulta Actualiza una puerta de enlace.
Llama a tools/list para verificar el conjunto de herramientas actualizado. Para ver un ejemplo de solicitud, consulta Descubre herramientas.
Después de que ninguna puerta de enlace use la configuración de la API anterior, borra la configuración de la API reemplazada:
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
Reemplaza OLD_CONFIG_ID por el ID de la configuración de la API reemplazada. No borres una configuración de API mientras una puerta de enlace la siga usando. Si tu nueva configuración de API cambia el nombre de las métricas de cuota o las quita, las puertas de enlace que aún entreguen una configuración de API anterior pueden devolver errores HTTP 500 hasta que se actualicen (consulta Las cuotas se aplican a toda la API). Para obtener más información, consulta Borra una configuración de API.

Ten en cuenta los siguientes comportamientos de lanzamiento y del cliente cuando actualices las herramientas de MCP:

Lanzamiento sin tiempo de inactividad: API Gateway actualiza las puertas de enlace sin tiempo de inactividad. Mientras se propaga la nueva configuración de la API, es posible que algunas solicitudes lleguen brevemente a la configuración anterior. Si tu API se implementa en varias puertas de enlace o regiones, actualiza cada puerta de enlace por separado.
Cachés de herramientas de cliente: Debido a que API Gateway entrega MCP a través de un transporte HTTP sin estado, la puerta de enlace no emite notificaciones de notifications/tools/list_changed. Una vez que se complete la actualización de la puerta de enlace, los clientes de MCP que almacenan en caché las definiciones de herramientas deben volver a llamar a tools/list para descubrir las herramientas actualizadas.
Límites de configuración de la API: Cada API está limitada a 100 parámetros de configuración de la API, por lo que debes borrar los parámetros de configuración de la API reemplazados después de actualizar las puertas de enlace. Crea configuraciones de API de una en una. Si inicias una segunda configuración de API para la misma API antes de que finalice la primera, es posible que una puerta de enlace no pueda usar una o ambas. Para obtener más información, consulta Cuotas y límites.

Observabilidad

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

Soluciona problemas de fallas del MCP

El MCP distingue entre fallas de transporte y fallas de protocolo. La puerta de enlace devuelve HTTP 200 con un objeto de error JSON-RPC para errores de protocolo y de aplicación, ya que las respuestas que no son 200 pueden hacer 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 JSON-RPC	Estado de HTTP	Significado y corrección típica
No se permite el método	No disponible	`405`	Una solicitud que no es POST llegó a `/mcp`. Solo se admite HTTP `POST`.
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 bien no son válidos	`-32600`	`200`	El cuerpo es un JSON válido, pero no es 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 de protocolo no compatible	`-32602`	`200`	El `protocolVersion` nombra una versión que la puerta de enlace no admite.
Falta la versión del protocolo	`-32602`	`200`	Los parámetros `initialize` omiten `protocolVersion` o no es una cadena.
Herramienta desconocida	`-32602`	`200`	No se encontró el nombre de la herramienta en la configuración de la API implementada. Actualiza la caché de la herramienta cliente o consulta Actualiza las herramientas de MCP expuestas.
Argumentos de la herramienta no válidos	`-32602`	`200`	Faltan argumentos o no son válidos. Verifica el anidamiento de claves de `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.
No autorizado/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.

Los errores de la aplicación de backend suelen aparecer como una respuesta JSON-RPC correcta (HTTP 200) con result.isError: true que contiene el cuerpo del error de backend.