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

Descripción general del Protocolo de contexto del modelo (MCP) en Apigee

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo usar Apigee para exponer tus APIs como herramientas de MCP a aplicaciones de agentes. El MCP en Apigee está disponible para organizaciones de suscripción, pago por uso y evaluación, incluidas las organizaciones con residencia de datos habilitada. A partir de la versión 1.17.0 de Apigee Hybrid, MCP también está disponible para Apigee Hybrid: el plano de datos del entorno de ejecución se ejecuta dentro de tu propio clúster de Kubernetes, en lugar de en la infraestructura administrada por Google. Consulta Habilita MCP en Apigee Hybrid para conocer el flujo de instalación y configuración específico de Hybrid.

¿Qué es el MCP?

El Protocolo de contexto del modelo (MCP) es un protocolo de código abierto desarrollado por Anthropic que estandariza la forma en que las aplicaciones de IA se conectan a fuentes de datos, flujos de trabajo y herramientas.

Las aplicaciones de IA pueden usar el MCP para acceder a los servicios de Google Cloud y Apigee como herramientas. En este contexto, es útil comprender los siguientes términos de MCP:

Host de MCP: Es la aplicación o el entorno de IA que interactúa con el usuario. El host de MCP usa modelos de lenguaje grandes (LLM) para procesar solicitudes que pueden requerir datos o herramientas externas.
Cliente de MCP: Es un componente dentro del host de MCP que ayuda a que el LLM y el servidor de MCP se comuniquen entre sí. Traduce las solicitudes del LLM para el servidor de MCP y convierte las respuestas del servidor de MCP para el LLM. También encuentra y usa los servidores de MCP disponibles.
Servidor de MCP: Es el servicio externo que proporciona contexto, datos o capacidades al LLM y actúa como proxy entre el LLM y el cliente de MCP.

Cómo funciona MCP en Apigee

Los extremos de MCP para Google, Google Cloudy Apigee implementan la especificación del servidor de MCP. Esto permite que los clientes de MCP que cumplen con los requisitos accedan a ellas para lo siguiente:

Descubre los extremos disponibles.
Enumera las herramientas disponibles en un extremo.
Autenticar en un extremo
Llamar a herramientas según las políticas de acceso definidas

Cualquier cliente de MCP que admita extremos de MCP remotos a través de HTTP/S puede acceder a estas herramientas. Como los extremos están administrados, no necesitas instalar ni administrar servidores de MCP locales, servidores de MCP remotos ni infraestructura adicional para permitir que las aplicaciones de agentes accedan a tus servicios.

MCP en Apigee ofrece compatibilidad con JSON-RPC para los métodos tools/list y tools/call. Puedes personalizar tu extremo de MCP con parámetros de visibilidad, seguridad, disponibilidad de red y observabilidad.

Modelos de implementación

MCP está disponible en dos modelos de implementación de Apigee:

Apigee (SaaS): El plano de datos de MCP se aloja en la infraestructura administrada por Google. Implementas el proxy de descubrimiento de MCP y el extremo está disponible de inmediato.
Apigee Hybrid (autohospedado, a partir de Apigee Hybrid 1.17.0): El plano de datos de MCP se ejecuta dentro de tu propio clúster de Kubernetes. El plano de control de Apigee genera la configuración de la herramienta de MCP a partir de tu especificación de OpenAPI, y tu clúster recupera esa configuración según su propio programa. El tráfico de solicitudes de MCP nunca sale de tu clúster. Consulta Habilita MCP en Apigee Hybrid.

Arquitectura del plano de datos de MCP en Apigee Hybrid

En el siguiente diagrama, se muestra cómo se distribuyen los componentes de MCP entre el plano de control de Apigee y tu clúster de Apigee Hybrid.

MCP en la arquitectura de Apigee Hybrid: Los clientes de MCP llaman a tu entrada de Apigee
existente a través de HTTPS, que se enruta a tu Message Processor y, luego, al
nuevo plano de datos de MCP en el clúster. La configuración de la herramienta de MCP la genera el
plano de control de Apigee y la extrae tu clúster. El plano de control de Apigee
nunca llama a tu clúster.

Dos propiedades de esta arquitectura son importantes para la planificación y la revisión de seguridad:

El tráfico de solicitudes de MCP permanece dentro del clúster. Los clientes de MCP acceden a tu entrada de Apigee existente en la misma URL que usarían para cualquier otro proxy de Apigee. Luego, tu Message Processor enruta la solicitud al plano de datos de MCP en el mismo clúster. Ninguna solicitud o respuesta de MCP cruza el límite hacia Google Cloud en el momento de la solicitud.
La configuración se extrae, no se envía. La configuración de la herramienta de MCP la genera el plano de control de Apigee y la recupera un componente de tu clúster según un programa. El plano de control de Apigee nunca inicia una conexión con tu clúster. Consulta Requisitos de red de salida para conocer los extremos exactos que debe permitir la salida del clúster.

Funciones clave de MCP en Apigee

El MCP en Apigee ofrece funciones para el descubrimiento, la seguridad y la administración de herramientas. Estas funciones te ayudan a administrar cómo interactúan las aplicaciones de agentes con tus servicios.

Descubrimiento de herramientas simplificado con el concentrador de APIs

Puedes descubrir los extremos de MCP disponibles para los servicios de Apigee con un servicio de directorio al que se puede acceder a través de una interfaz de REST. Cada extremo de MCP también admite el método tools/list de MCP, que permite que los clientes de MCP descubran las herramientas disponibles en ese extremo.

Además, el MCP se integra en el Centro de APIs de Apigee. Cuando se implementa un proxy de descubrimiento de MCP, el concentrador de APIs transfiere automáticamente su especificación de OpenAPI, le asigna el estilo de API de MCP y asigna las operaciones de la API a herramientas de MCP individuales. Esto permite que los desarrolladores filtren fácilmente las APIs habilitadas para MCP en el concentrador de APIs y usen la búsqueda semántica con consultas en lenguaje natural para encontrar herramientas pertinentes para sus aplicaciones de agentes.

Ubicación del argumento de la herramienta en la solicitud de backend

Cuando un cliente de MCP llama a una herramienta, Apigee compila una solicitud para tu backend a partir de los argumentos que proporcionó el cliente. El valor in que declara cada parámetro en tu especificación de OpenAPI determina dónde se coloca ese argumento en la solicitud saliente.

Valor `in` de OpenAPI	Dónde se envía el argumento en la solicitud de backend
`header`	Como un encabezado de solicitud El nombre del parámetro se usa como el nombre del encabezado exactamente como se escribe en la especificación.
`cookie`	En el encabezado de la solicitud `Cookie`, como un par `name=value`. Si una operación declara varios parámetros de cookie, se envían en un encabezado `Cookie`, separados por `;` (un punto y coma y un espacio).
`query`	En la cadena de consulta
`path`	Se sustituye en la ruta de URL de la solicitud.

Cada parámetro aparece en el inputSchema de la herramienta, independientemente de su valor in, por lo que un cliente de MCP los proporciona todos de la misma manera. El valor in cambia solo donde se coloca el valor en la solicitud a tu backend.

Por ejemplo, la siguiente operación declara un parámetro en cada una de las tres ubicaciones:

paths:
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: X-Session-Id
          in: header
          schema:
            type: string
        - name: tenantId
          in: cookie
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer

Una solicitud tools/call que proporciona los tres argumentos produce una solicitud de backend con la siguiente forma:

GET /orders?limit=25
X-Session-Id: sess-abc-123
Cookie: tenantId=tenant-xyz-789

Ten en cuenta el siguiente comportamiento:

Un argumento vinculado a un encabezado o una cookie tampoco se agrega a la cadena de consulta y no se incluye en el cuerpo de la solicitud.
Se omite un argumento que el cliente no proporciona. No se envía ningún encabezado, cookie ni parámetro de consulta vacío en su lugar.
Un encabezado vinculado reemplaza cualquier encabezado con el mismo nombre que ya esté en la solicitud de backend. Otros encabezados de la solicitud de backend se pasan sin cambios.
Los valores se codifican en porcentaje (RFC 3986) cuando se colocan en la solicitud del backend, por lo que un valor que contiene un espacio o un carácter reservado llega al backend en su formato codificado. Decodifícalo allí si necesitas el original.
Cuando una operación y su ruta de acceso declaran un parámetro con el mismo nombre y el mismo valor in, se aplica la declaración a nivel de la operación, como lo requiere la especificación de OpenAPI.
Asigna nombres distintos a los parámetros de la misma operación, incluso cuando declaren valores in diferentes. OpenAPI identifica un parámetro por el par de su nombre y su ubicación, pero una herramienta de MCP toma un solo valor por nombre de argumento. Si una especificación declara dos parámetros con el mismo nombre y diferentes valores de in, el cliente proporciona un valor y ese valor se envía a ambas ubicaciones declaradas en la solicitud del backend: un sessionId declarado como in: cookie y in: query llega en el encabezado Cookie y en la cadena de consulta. Verifica esto si tu backend tiene lógica que depende de dónde provino un valor.
Los nombres de los argumentos distinguen mayúsculas de minúsculas, por lo que UserID y userid son dos argumentos diferentes. En el caso de los parámetros header, da un paso más y haz que los nombres difieran en algo más que mayúsculas y minúsculas: los nombres de los encabezados HTTP no distinguen mayúsculas de minúsculas, por lo que dos parámetros de encabezado cuyos nombres solo difieren en mayúsculas y minúsculas se resuelven en el mismo encabezado en la solicitud de backend y solo uno de los dos valores sobrevive.

Las cookies son el único caso en el que la vinculación puede quitar algo de la solicitud en lugar de solo agregarle algo. A diferencia de otros encabezados HTTP, que llevan pares de nombre/valor independientes que se pueden establecer por separado, todas las cookies comparten un solo encabezado Cookie. Apigee no combina las cookies que vinculas con las que llegaron en la solicitud del cliente de MCP: cuando una llamada proporciona cualquier argumento de cookie, el encabezado Cookie se reemplaza por completo solo con las cookies vinculadas.

Por lo tanto, si una cookie que llegó con la solicitud HTTP del cliente de MCP alcanza tu backend, dependerá de la llamada a la herramienta individual:

Si la operación no declara parámetros cookie, el encabezado Cookie se reenvía al backend sin cambios.
Si la operación declara parámetros cookie, pero la llamada no proporciona ninguno de ellos, el encabezado Cookie se vuelve a reenviar al backend sin cambios.
En cuanto la llamada proporciona al menos un argumento de cookie, el encabezado Cookie se reemplaza solo por las cookies vinculadas. Se descarta cualquier cookie que haya llegado en la solicitud del cliente y no se declare como un parámetro cookie.

Debido a que el tercer caso se basa en los argumentos que proporciona una llamada en particular, una operación con parámetros de cookies opcionales puede pasar cookies en una llamada y descartarlas en la siguiente. No hay ningún parámetro de configuración que conserve una cookie no declarada. Si tu backend depende de una cookie, declárala como un parámetro cookie en cada operación que la necesite, de modo que su valor siempre lo proporcione la llamada a la herramienta en lugar de heredarlo de la solicitud del cliente.

Seguridad

MCP en Apigee incluye varias capas de seguridad para proteger tus servicios. Puedes controlar el acceso con la autenticación, la autorización, los límites de red y el análisis de contenido.

Autenticación

Los extremos de MCP alojados en Apigee admiten OAuth 2.1 y OpenID Connect (OIDC) para la autenticación. Esto garantiza que solo los agentes, los clientes de MCP y los usuarios finales con identidades establecidas puedan acceder a tus extremos de MCP y llamar a las herramientas de MCP. Los metadatos de recursos protegidos permiten que los clientes descubran los servidores de autorización de OAuth.

Políticas de autorización detalladas

Puedes restringir el acceso a tus herramientas de MCP según las identidades de los clientes de OAuth. Por ejemplo, puedes configurar una política en tu proxy de descubrimiento de MCP para especificar que solo los agentes designados con identidades de cliente conocidas puedan acceder a una herramienta de MCP para un servicio de pagos.

Responsabilidad del cliente por las invocaciones de herramientas

Las aplicaciones cliente de MCP son responsables de aplicar la supervisión humana de las invocaciones de herramientas, como solicitarle al usuario que confirme antes de ejecutar operaciones que muten el estado. Para obtener más información, consulta la documentación del protocolo de contexto del modelo.

Observabilidad y estadísticas

En el caso de los extremos alojados en Apigee, puedes usar Apigee Analytics para ver información de uso detallada de tus herramientas de MCP. Analytics te permite segmentar el tráfico específico del MCP del tráfico de la API estándar y ver las métricas a nivel de la herramienta individual, como el volumen de solicitudes de tools/list (descubrimiento) en comparación con las de tools/call (ejecución). Las métricas de rendimiento también te ayudan a distinguir entre la sobrecarga del proxy y el tiempo de respuesta del destino, lo que te permite identificar los cuellos de botella con mayor eficacia.

Confiabilidad y solución de problemas

Para mejorar la solución de problemas y proporcionar más visibilidad del proceso de implementación, Apigee muestra errores específicos de infraestructura y configuración en la IU. Si una implementación falla debido a una especificación de OpenAPI no válida o un problema de infraestructura regional, la IU proporcionará comentarios prácticos para ayudarte a resolver el problema sin necesidad de que intervenga el equipo de asistencia.

Usa MCP con Apigee

Puedes exponer tus APIs de Apigee existentes como herramientas de MCP y hacer que se pueda acceder a ellas a través de endpoints de MCP. Estos extremos se pueden configurar por host o por grupo de entornos. Por ejemplo, si tu organización de cymbal tiene ocho nombres de host (p.ej., api.cymbal.com, partners.cymbal.com), cada uno asociado con un grupo de entornos diferente, puedes alojar un servidor de MCP dedicado para cada nombre de host.

Un extremo de destino administrado (ORG_NAME.mcp.apigee.internal) se implementa con un proxy de descubrimiento de MCP especializado en tu organización de Apigee, donde tus servidores de MCP están disponibles.

Nota (solo para Apigee Hybrid): En Apigee Hybrid, el extremo de destino se resuelve en el Service del plano de datos de MCP en el clúster (etiquetado como app=apigee-mcp-server) dentro de tu clúster, no en un extremo administrado por Google. Se admiten dos URLs de destino equivalentes:

https://ORG_NAME.mcp.apigee.internal/mcp (recomendada)
https://mcp.apigee.internal/mcp (retrocompatible)

Ambos se resuelven en el mismo plano de datos de MCP en el clúster. El plano de control de Apigee también genera el extremo de destino del proxy de descubrimiento de MCP con el formato con alcance de organización (ORG_NAME.mcp.apigee.internal). Se prefiere este formato en cualquier código de cliente o proxy personalizado para que la URL que crees coincida con la URL que genera la plataforma y para que los registros y los seguimientos hagan explícito el límite del usuario.

En la siguiente tabla, se muestra un ejemplo de cómo los clientes, incluida la organización ficticia Cymbal, pueden configurar varios extremos de MCP con Apigee.

Cliente	Nombre de host y ruta de acceso base de MCP	Extremo de destino del servidor de MCP	proxy de API	Entorno / grupo de entornos
platillo	`api.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (proyecto de usuario de la organización de Cymbal)	`mcp-api-proxy1`	`prod`/`prod-env-group`
	`api-internal.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (proyecto de usuario de la organización de Cymbal)	`mcp-api-proxy2`	`internal`/`internal-env-group`
	`api-service.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (proyecto de usuario de la organización de Cymbal)	`mcp-api-proxy3`	`dev`/`dev-env-group`

Limitaciones

Se aplican las siguientes limitaciones a MCP en Apigee:

La cantidad de herramientas de MCP en una organización de Apigee está limitada a 1,000.
La implementación de la infraestructura de MCP puede estar sujeta a limitaciones de capacidad en las siguientes regiones:
- europe-central2
- europe-southwest1
- europe-west9
- me-central2
Si ves un error de aprovisionamiento o el estado de aprovisionamiento nunca cambia a Implementado, es posible que se deba a límites temporales de capacidad de la infraestructura en la región seleccionada. Intenta implementar el proxy en un entorno de otra región.
El MCP en Apigee admite las siguientes versiones de OpenAPI: 3.0.0, 3.0.1, 3.0.2, 3.0.3.
Las estadísticas de la API en el centro de APIs de Apigee no están disponibles para las APIs y herramientas de MCP implementadas en organizaciones de Apigee con VPC-SC habilitado.
Las llamadas GET en las respuestas de error de MCP devolverán un error 405, ya que el servidor de MCP actualmente no admite transmisiones de eventos enviados por el servidor (SSE).
Las estadísticas de la API del centro de APIs de Apigee no mostrarán las APIs de estilo MCP ni el tráfico de los recursos de MCP hasta que la versión 1-17-0-apigee-6 de Apigee se lance por completo en todas las regiones disponibles.
No puedes cambiar el atributo de estilo de la API a MCP para un recurso de API que tenga operaciones de API existentes.

Limitaciones específicas de Apigee Hybrid

Se aplican las siguientes limitaciones al MCP en Apigee Hybrid:

Los argumentos de la herramienta declarados como in: header o in: cookie se envían en la cadena de consulta. El enrutamiento por ubicación descrito en Ubicación de los argumentos de la herramienta en la solicitud al backend aún no está disponible en Apigee Hybrid. Hasta que lo haga, un parámetro que declare cualquiera de esas ubicaciones llegará a tu backend como un parámetro de consulta, que es el comportamiento que precedió a esa función. Las filas in: query y in: path de esa tabla se aplican a Apigee Hybrid como se indica.
La cantidad de herramientas de MCP está limitada por el tamaño, no por un número fijo. A diferencia de Apigee (que aplica una cantidad máxima fija de herramientas de MCP por organización), Apigee Hybrid limita la capacidad de las herramientas a través de cuatro límites de tamaño: el tamaño del archivo de especificación de OpenAPI, el tamaño del paquete de proxy de MCP, el tamaño de la respuesta de tools/list por nombre de host y la cantidad de nombres de host por grupo de entornos. En la mayoría de las especificaciones de OpenAPI, puedes esperar que se ajusten 10,000 herramientas de MCP por organización con el límite de tamaño de respuesta predeterminado. La capacidad real varía según la forma específica de tu especificación (dominada por la cantidad de parámetros y propiedades del cuerpo de la solicitud, además de la longitud de la descripción). Los esquemas de respuesta no se tienen en cuenta para el presupuesto. Para estimar la capacidad de tus especificaciones de OpenAPI concretas y ver los cuatro límites estrictos y sus modos de falla, consulta Estima la capacidad de la herramienta de MCP.
Cuando habilitas o inhabilitas MCP, se activa un lanzamiento canary por etapas de los Pods de Message Processor. El operador de Apigee actualiza la especificación del Pod del Message Processor cuando habilitas o inhabilitas MCP, y el controlador ApigeeDeployment del Message Processor ejecuta el cambio a través de un lanzamiento Canary por etapas, en lugar de un reinicio progresivo de Kubernetes estándar. La versión se activa solo en las transiciones de habilitación e inhabilitación, no en la actividad de implementación de MCP en curso ni en el tráfico de MCP en estado estable. Programa la habilitación inicial y cualquier operación de inhabilitación posterior durante un período de mantenimiento aprobado.
El cliente administra el tamaño de los recursos de los Pods de MCP. Los Pods de MCP se ejecutan con las solicitudes y los límites de recursos que se establecen con los valores predeterminados integrados en los gráficos de Helm de Apigee Hybrid. Si tu carga de trabajo requiere más capacidad, ajusta la CPU y la memoria en overrides.yaml. Consulta la referencia de campos de overrides.yaml para ver los campos disponibles.
Un plano de datos de MCP por organización de Apigee y por clúster. En la versión 1.17.0, el operador de Apigee aprovisiona un plano de datos de MCP para cada organización de Apigee instalada en el clúster. Un clúster que aloja varias organizaciones de Apigee ejecuta un plano de datos de MCP por organización. Los planos de datos son independientes y no comparten la configuración.
Se requiere la habilitación uniforme en un grupo de entornos. Habilita MCP de manera uniforme en todos los clústeres que entregan el mismo grupo de entornos de Apigee. Si MCP está habilitado en algunos clústeres y no en otros dentro de un grupo, las solicitudes de MCP que se enrutan a un clúster sin MCP habilitado recibirán una respuesta 503 Service Unavailable.
TLS unidireccional entre el Message Processor y el plano de datos de MCP. La versión 1.17.0 usa TLS unidireccional entre el Message Processor y el plano de datos de MCP.
El plano de datos de MCP depende del Message Processor para la identidad del emisor. El plano de datos de MCP en el clúster no autentica de forma independiente a sus emisores en 1.17.0; confía en que las solicitudes que llegan ya se autenticaron con un proxy de Apigee que se ejecuta en Message Processor. Cada solicitud de MCP que deba autenticarse debe llegar a través de un proxy de MCP de Apigee que aplique una política de autenticación (consulta Administra el acceso a las herramientas de MCP). Los clientes de producción deben aplicar controles de entrada de clúster para que solo los Pods de Message Processor (etiqueta de Kubernetes app=apigee-runtime en el mismo espacio de nombres de Kubernetes en el que se instala Apigee Hybrid) puedan acceder al servicio de MCP en TCP 443. Usa cualquier motor de políticas que admita tu plataforma (NetworkPolicy de Kubernetes, Cilium, Calico, AuthorizationPolicy de Istio) para aplicar esta restricción.

¿Qué sigue?

Obtén más información para comenzar a usar Apigee y MCP.
Para Apigee Hybrid, primero habilita MCP en tu clúster y, luego, sigue la guía de inicio rápido.
Para acceder a otros productos de Google y Google Cloud a través de las herramientas de MCP, consulta la Descripción general de los servidores de MCP de Google Cloud

Descripción general del Protocolo de contexto del modelo (MCP) en Apigee Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.