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 solucionar problemas relacionados con la implementación de proxies de descubrimiento de MCP. Puedes usar esta página para comprender el ciclo de vida del aprovisionamiento asíncrono de las implementaciones de MCP, resolver códigos de error y verificar la conectividad del entorno de ejecución.
Comprende la implementación de MCP
La implementación de un proxy de descubrimiento de MCP es un proceso asíncrono de varios pasos que garantiza que la configuración se propague por completo en la infraestructura de Apigee y Google Cloud antes de que se complete la implementación del proxy.
Mientras se realizan estos pasos de aprovisionamiento downstream, la IU muestra el proxy en un estado de Aprovisionamiento. Cuando se complete el proceso, el estado cambiará a Implementado. Este estado confirma que todos los componentes downstream están completamente aprovisionados y que el proxy está listo para controlar el tráfico.
Soluciona problemas
En las siguientes secciones, se describen los errores y los problemas conocidos que puedes encontrar cuando usas MCP en Apigee.
El backend no recibe un argumento de herramienta en la ubicación esperada
Problema: Un backend lee un argumento de herramienta de una ubicación de solicitud (la cadena de consulta, un encabezado o una cookie), pero la especificación de OpenAPI declara el parámetro in en una ubicación diferente, por lo que el argumento llega a otro lugar en la solicitud del backend. La llamada falla o
se comporta como si el argumento no estuviera presente.
Síntomas: La solicitud tools/call se realiza correctamente en la capa de MCP
y el cliente de MCP proporciona el argumento, pero el backend responde como
si faltara el valor, por ejemplo, un 400 para un
valor obligatorio o un valor predeterminado que se aplica en lugar del valor enviado.
Causa: El parámetro se declara como in: header o
in: cookie en la especificación de OpenAPI, por lo que Apigee envía
su valor como un encabezado de la solicitud o en el encabezado Cookie en lugar de
en la cadena de consulta. Un backend que lee el valor solo de la cadena de consulta
no lo ve. Consulta
Ubicación
del argumento de la herramienta en la solicitud de backend.
Solución: Decide a dónde pertenece el valor y haz que la especificación y el backend coincidan:
- Para mantener el valor en la cadena de consulta, declara el parámetro
in: query. - Para enviarlo como un encabezado o una cookie, deja la declaración como está y lee el valor de esa ubicación en tu backend.
El backend deja de recibir una cookie que llevaba la solicitud del cliente de MCP
Problema: Una cookie que llega en la solicitud HTTP que realiza el cliente de MCP (por ejemplo, una cookie de sesión de un cliente basado en un navegador) deja de llegar al backend en algunas llamadas a la herramienta.
Síntomas: El backend se comporta como si el emisor no estuviera autenticado o no estuviera en sesión, y el comportamiento es incoherente: la misma operación funciona en algunas llamadas y no en otras.
Causa: La operación declara uno o más parámetros in: cookie,
y las llamadas afectadas proporcionaron al menos uno de ellos. El encabezado Cookie se reescribe en su totalidad en lugar de agregarse, por lo que, en esas llamadas, solo lleva los parámetros de cookie declarados y se descartan todas las demás cookies. Las llamadas que no proporcionaron ninguno de los parámetros de cookie pasan el encabezado sin modificar, por lo que solo fallan algunas llamadas. Consulta
Cookies
en la solicitud a tu backend.
Resolución: Declara cada cookie que el backend necesita como un parámetro in: cookie en cada operación que la requiera, de modo que su valor siempre se proporcione a través de la llamada a la herramienta en lugar de heredarse de la solicitud del cliente. No hay ningún parámetro de configuración que conserve una cookie no declarada.
Códigos de estado de respuesta de error para llamadas a la herramienta y metadatos
Los extremos de MCP de Apigee devuelven códigos de estado HTTP que siguen la especificación del Protocolo de contexto del modelo (MCP) y los estándares de OAuth relacionados. Comprender este comportamiento te ayuda a controlar correctamente los errores en tu cliente de MCP o agente de IA.
En la siguiente tabla, se resumen los códigos de estado que devuelven los extremos de MCP de Apigee:
| Situación | Código de estado HTTP | Cuerpo de la respuesta |
|---|---|---|
La ejecución de una herramienta falla en tools/call (por ejemplo, la
API de backend devuelve un error 4xx o 5xx, como un
error de validación o un campo obligatorio faltante). |
200 OK |
Un CallToolResult con result.isError establecido en
true y los detalles del error en content. Esto permite que el
cliente de MCP y el agente de LLM lean el error y se recuperen (por ejemplo, volviendo a solicitar la entrada faltante y reintentando) en lugar de finalizar la
sesión. |
Los metadatos de recursos protegidos (PRM) de OAuth no están configurados o no se pueden
encontrar en /.well-known/oauth-protected-resource/mcp. |
404 Not Found |
Indica que no hay metadatos de recursos protegidos disponibles en la ubicación solicitada. |
| Falta el token de acceso, no es válido o venció. | 401 Unauthorized |
Incluye un desafío WWW-Authenticate para impulsar el flujo de descubrimiento de OAuth. |
| El token de acceso tiene un permiso insuficiente. | 403 Forbidden |
Incluye un desafío de WWW-Authenticate para impulsar el flujo de autorización de
step-up. |
Ejemplo: Cuerpo de la respuesta de error de ejecución de la herramienta
Cuando falla una llamada a la herramienta, el MCP de Apigee devuelve HTTP 200 OK y
informa la falla en el objeto result de JSON-RPC, con
isError configurado como true. El error original que muestra tu
backend se conserva: el cuerpo de la respuesta del backend se coloca de forma textual (como una cadena)
en result.content[].text. Por ejemplo, si el backend devuelve
HTTP 404 con el cuerpo {"error":"User 42 not found"}, la respuesta de MCP
es la siguiente:
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"error\":\"User 42 not found\"}" } ], "isError": true } }
El id coincide con el id de tu solicitud tools/call.
Si el backend no devuelve un cuerpo de respuesta, text contiene un resumen generado, como Operation failed (HTTP 500).
Tu cliente de MCP debe inspeccionar result.isError (no el código de estado HTTP)
para detectar una llamada a la herramienta fallida. Si tu código de cliente espera específicamente un estado HTTP 4xx o 5xx para indicar un error de ejecución de la herramienta, no detecta el error, porque la respuesta es HTTP 200 OK. Actualiza esos clientes para que lean result.isError y el array content.
Los errores a nivel del protocolo (por ejemplo, una solicitud JSON-RPC con formato incorrecto) son distintos de
los errores de ejecución de la herramienta: se siguen devolviendo en el objeto error de JSON-RPC (por ejemplo, {"jsonrpc": "2.0", "error": {"code": -32700, ...}})
en lugar de en result.isError.
Recomendación: Los clientes de MCP que cumplen con los estándares controlan estos códigos de estado
a través de su lógica predeterminada, por lo que no se requieren cambios. Si anteriormente agregaste una
solución alternativa del cliente para controlar los códigos de estado no estándar (por ejemplo, analizar
un cuerpo de respuesta que no sea 2xx para errores tools/call o tratar una
respuesta 500 del extremo de PRM como "metadatos no configurados"), te
recomendamos que quites esa solución alternativa. De lo contrario, es posible que tu cliente siga usando
la lógica de manejo obsoleta en lugar de procesar los códigos de estado corregidos con normalidad.
Política de CORS para llamadas de MCP basadas en el navegador
Se necesita una política de uso compartido de recursos entre dominios (CORS) cuando las llamadas al MCP de Apigee se realizan directamente desde un navegador (por ejemplo, cuando el inspector de MCP usa el parámetro de configuración "Directo" en lugar de "A través de un proxy"). La plantilla de proxy de descubrimiento de MCP incluye la política de CORS de Apigee en el PreFlow de solicitud del extremo del proxy del paquete de proxy de forma predeterminada para habilitar las llamadas basadas en el navegador.
Si tienes problemas relacionados con CORS cuando realizas llamadas directamente desde un navegador, es posible que debas ajustar la configuración de la política de CORS en el flujo previo de solicitud del extremo del proxy de tu paquete de proxy de MCP Discovery.
Error de análisis de JSON cuando se envía una solicitud al extremo de MCP
Es posible que recibas un mensaje de error similar al siguiente (o con un código de error y un mensaje diferentes) cuando envíes una solicitud a tu extremo de MCP:
{
"error": {
"code": -32700,
"message": "JSON parse error"
},
"id": null,
"jsonrpc": "2.0"
}En ese caso, te recomendamos que confirmes la siguiente información:
- Ingresaste la URL de extremo de MCP correcta.
- Tu solicitud tiene el formato correcto.
- Estás accediendo a un método compatible.
- Habilitaste y configuraste tu proxy de descubrimiento de MCP en una región admitida. Para obtener una lista de las regiones que pueden tener límites de capacidad, consulta fallas de implementación.
Fallas de Deployment
Si la implementación del proxy de descubrimiento de MCP falla con el estado Fallido en la IU, consulta el mensaje de error para obtener más detalles. Entre las fallas comunes, se incluyen las siguientes:
- Error en la configuración de red o Esquema no compatible en OAS: Estos errores suelen indicar un problema con la especificación de OpenAPI. Asegúrate de que tu especificación sea válida y use una versión compatible.
- Límites de capacidad de la región (solo Apigee): Si ves un error relacionado con una falla de aprovisionamiento del balanceador de cargas o el estado de aprovisionamiento nunca cambia a Implementado, es posible que se deba a límites de capacidad de infraestructura temporales en una de las siguientes regiones:
asia-east2asia-northeast3asia-southeast2australia-southeast1europe-central2europe-west12europe-west9me-central2us-central2
Para resolver el error, intenta implementar el proxy en un entorno de otra región. Este modo de falla no se aplica a Apigee Hybrid, en el que la infraestructura del entorno de ejecución es tu propio clúster.
- MCP no habilitado en el clúster (solo Apigee Hybrid): Si la implementación del proxy de MCP permanece en el estado Aprovisionando de forma indefinida y nunca llega a Implementado, verifica que MCP esté habilitado en tu clúster. Consulta Diagnóstico del lado del clúster a continuación.
Diagnóstico del lado del clúster (solo Apigee Hybrid)
Debido a que el plano de datos de MCP de Apigee Hybrid se ejecuta dentro de tu propio clúster de Kubernetes,
los modos de falla dentro del clúster se diagnostican con kubectl en el clúster.
Revisa la siguiente lista de tareas de diagnóstico en orden.
Paso 1: Verifica que MCP esté habilitado en el clúster
MCP se implementa como un recurso personalizado de ApigeeDeployment (administrado por el
operador de Apigee), no como un Deployment de Kubernetes básico. Verifica
el MCP ApigeeDeployment:
kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server
Resultado esperado (los nombres de los recursos incluyen un sufijo derivado de la organización, que se muestra aquí como
ORG_CR_SUFFIX):
NAME STATE NESTEDSTATE AGE apigee-mcp-server-default-ORG_CR_SUFFIX running 1h
Si el comando devuelve No resources found in APIGEE_NAMESPACE namespace.,
MCP no está habilitado. Regresa a
Habilita MCP en Apigee Hybrid y
verifica que enableMcpServer: true esté configurado como una clave de nivel superior en tu
overrides.yaml y que hayas actualizado la versión de Helm
apigee-operator antes de la versión apigee-org. Consulta el
paso 3
y el paso 4
del procedimiento de habilitación para obtener los comandos de helm correctos.
Paso 2: Verifica que los Pods de MCP se estén ejecutando
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server
Resultado esperado (los sufijos de los Pods serán diferentes):
NAME READY STATUS RESTARTS AGE apigee-mcp-server-default-ORG_CR_SUFFIX-1170-abcd1234 2/2 Running 0 1h apigee-mcp-server-default-ORG_CR_SUFFIX-1170-efgh5678 2/2 Running 0 1h
Los nombres de los Pods siguen la plantilla
apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH,
en la que REV es la revisión de la versión híbrida de cuatro dígitos (por ejemplo, 1170
para la versión híbrida 1.17.0) y POD_HASH es un sufijo alfanumérico de ocho caracteres que
es diferente para cada Pod.
Cada Pod debe mostrar 2/2 en la columna READY y
Running en la columna STATUS. Si los Pods no están en estado Running,
kubectl -n APIGEE_NAMESPACE describe pod POD_NAME muestra
el motivo. Las causas comunes son fallas de extracción de imágenes (verifica la salida de tu clúster al
registro de imágenes configurado en tu overrides.yaml) y un margen de CPU o
memoria insuficiente (aumenta mcpServer.resources.requests en
overrides.yaml).
Paso 3: Verifica el estado de extracción de la configuración del archivo adicional
El contenedor sidecar apigee-mcp-server-config en cada Pod de MCP
extrae de forma periódica la configuración de MCP del plano de control de Apigee. Cada extracción recupera
la referencia de configuración actual de apigee.googleapis.com y, luego,
recupera el paquete de configuración al que se hace referencia desde Cloud Storage. El plano de datos de MCP
comienza a entregar tráfico de herramientas de MCP en https://mcp.apigee.internal/mcp una vez que
se completa correctamente una extracción con una configuración válida.
Antes de esa primera extracción exitosa con una configuración válida (ya sea porque aún no se implementó
ningún proxy de descubrimiento de MCP para tu organización o porque el archivo adicional
no puede alcanzar el plano de control), los Pods de MCP permanecen en estado Ready, pero las solicitudes a
https://mcp.apigee.internal/mcp fallan con el mensaje conexión rechazada.
Inspecciona los registros del archivo adicional para determinar en qué caso te encuentras:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
- Repite la línea
infoque indica que no hay configuración de MCP desde el plano de control: El plano de control de Apigee devolvió una respuesta correcta, pero aún no se implementó ningún proxy de descubrimiento de MCP para tu organización. Este es el estado estable esperado durante la incorporación. Para que el plano de datos de MCP pase al estado de entrega, implementa un proxy de descubrimiento de MCP según la guía de inicio rápido de MCP.{"level":"info","ts":1787582542.68,"caller":"mcpsidecar/sidecar.go:397","msg":"mcpsidecar: no MCP config from CP yet; skipping tick, pod stays Ready via seed","org":"YOUR_ORG","mcp_server_id":"default"} - Línea
errorcon un contadorconsecutive_failures: Los registros de sidecar son JSON estructurados. Cuando veas{"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}"level":"error"con un contadorconsecutive_failuresen aumento, el archivo adicional no pudo completar una extracción de configuración. El archivo adicional vuelve a intentarlo de forma automática con una retirada y restablece el contador a 0 en la siguiente extracción correcta.Estas son las causas raíz comunes que debes verificar cuando este contador sigue aumentando:
- La cuenta de servicio de Google Cloud
apigee-watcherno está en la listawatcher_identitiesdel recursocontrolPlaneAccessde tu organización de Apigee. Consulta el paso 2: Otorga acceso a la identidad del observador a la configuración de MCP en el plano de control en el procedimiento de habilitación para agregar el otorgamiento y verificar que se haya aplicado. - La salida de tu clúster a
apigee.googleapis.comostorage.googleapis.comestá bloqueada. Se debe poder acceder a ambos extremos desde los Pods de MCP (consulta Requisitos de red saliente en el procedimiento de habilitación). - La cuenta de servicio
apigee-watcherno puede obtener tokens de acceso de Google Cloud desde este clúster. Si los componentes existentes de Apigee Hybrid en el mismo espacio de nombres también informan fallas de autenticación, primero soluciona el problema de autenticación compartido. - Un error transitorio del plano de control de Apigee o de Cloud Storage. Si el contador sigue aumentando durante un período prolongado después de descartar las causas anteriores, comunícate con el equipo de asistencia de Apigee.
- La cuenta de servicio de Google Cloud
Paso 4: Verifica que se hayan insertado los hostAliases del Message Processor
Cuando habilitas el MCP, el operador de Apigee inserta una entrada hostAliases en la especificación del Pod del Message Processor (MP). La entrada contiene una IP (la ClusterIP del servicio de MCP) y dos nombres de host: mcp.apigee.internal y ORG_NAME.mcp.apigee.internal en minúsculas. Verifica que la inserción se haya realizado correctamente:
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
Cada Pod de MP de la lista debe tener una entrada hostAliases que contenga
mcp.apigee.internal y ORG_NAME.mcp.apigee.internal en minúsculas
que apunten a la ClusterIP del servicio de MCP. Cualquier
pod de MP que muestre una entrada vacía o faltante se creó antes de que se habilitara MCP. Borra
el Pod de MP afectado para que el controlador de ApigeeDeployment lo vuelva a crear a partir de la
especificación del Pod actual (que incluye la entrada hostAliases insertada):
kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime
Paso 5: Verificación de extremo a extremo
Para realizar una prueba de extremo a extremo que envíe una solicitud de MCP initialize real a través
del plano de datos de MCP, implementa un proxy de descubrimiento de MCP y sigue la
guía de inicio rápido de MCP.
Antes de que se implemente un proxy de descubrimiento de MCP para tu organización, las solicitudes a
https://mcp.apigee.internal/mcp fallan con el mensaje conexión rechazada,
independientemente de si Message Processor puede alcanzar los Pods de MCP (consulta el paso 3).
Paso 6: Verifica mTLS en la puerta de enlace de entrada (si está configurada)
Este paso solo se aplica si configuraste
virtualhosts[].mcpMtls
para un grupo de entornos (Apigee Hybrid 1.17.4 y versiones posteriores). El síntoma típico
de un problema de mTLS es que las llamadas de la herramienta de MCP a un grupo de entornos fallan
(por lo general, 503 Service Unavailable), mientras que las llamadas a otros grupos de entornos
se realizan correctamente, ya que el plano de datos de MCP mantiene su configuración de certificado por grupo de
entornos.
- Confirma que el operador aceptó el campo. El recurso de enrutamiento del grupo de entornos debe llevar el bloque
mcpMtls: Una segunda columna vacía, varios minutos después de la actualización dekubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
apigee-virtualhost, suele significar que las definiciones de recursos personalizados de Apigee en el clúster son anteriores a1.17.4y no declaranmcpMtls, por lo que el servidor de la API descartó el campo. (Con menos frecuencia, el gráficoapigee-orgque proporciona la imagen del observador no se actualizó a1.17.4). Esto sucede cuando se ejecutó una actualizaciónhelm upgradepara el gráfico del operador, pero se omitió el paso Instala las CRD de Apigee actualizadas. Luego, el plano de datos de MCP sigue usando TLS unidireccional, y la puerta de enlace de entrada en el modoMUTUALlo rechaza. Los mismos CRD obsoletos también evitan que se informen los problemas deAIS_MCP_MTLS_*en el siguiente paso. Verifica y corrige con lo siguiente: Ejecutakubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls # 0 means the CRDs are stale kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
kubectl applydesde el directorio de gráficos de Helm y, luego, vuelve a ejecutar la actualización deapigee-virtualhostpara el grupo de entornos. - Verifica si hay problemas con los certificados que informa el clúster. El observador analiza los
Secrets configurados y crea un
ApigeeIssuepara cada problema: El campokubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)' kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
Spec.Detailsnombra el Secret y elApigeeRouteConfig(llamadoORG_NAME-ENV_GROUP_NAME) al que pertenece el problema, y el defecto específico.
Los problemas se retiran automáticamente en el siguiente análisis después de que se corrige el Secret.Motivo Gravedad Significado Corregir AIS_MCP_MTLS_CLIENT_CERT_INVALIDERROREl Secret del certificado de cliente no existe ( secret not found), falta una entradacertokey, una entrada está vacía o no es PEM, el certificado y la clave no coinciden, o el uso de la clave extendida del certificado omiteclientAuth. El plano de datos de MCP no lo carga.Crea o corrige el Secret (opción 2) o los archivos seguidos de helm upgrade(opción 1). Si el problema es el uso extendido de la clave, vuelve a emitir el certificado conclientAuth.AIS_MCP_MTLS_CLIENT_CERT_EXPIRYWARNINGen un plazo de 14 días antes del vencimiento;ERRORdespuésEl certificado de cliente está a punto de vencer o ya venció. Aún se presenta un certificado vencido; la puerta de enlace de entrada rechaza el protocolo de enlace. Rota el certificado como se describe en Rota certificados. AIS_MCP_MTLS_CA_CERT_INVALIDERROREl Secret -cacertno existe (secret not found; consslSecret, lo creas tú), falta su entradacacert, la entrada no es PEM, un bloque no es un certificado o un certificado que contiene no es un certificado de la AC.Crea el Secret si es necesario y coloca el certificado de la AC (o cadena) que firmó el certificado de la puerta de enlace de entrada en la entrada cacert.AIS_MCP_MTLS_CA_CERT_EXPIRYWARNINGen un plazo de 14 días antes del vencimiento;ERRORdespuésUn certificado de la AC en el Secret -cacertestá por vencer o ya venció. Después del vencimiento, el plano de datos de MCP ya no confía en la cadena de certificados de la puerta de enlace de entrada.Reemplaza el certificado de la AC en el Secret -cacertantes de que venza, junto con el certificado propio de la puerta de enlace de entrada si también se vuelve a emitir. - Lee los mensajes de mTLS del archivo adicional. El contenedor
apigee-mcp-server-configregistra una líneaerrorcada vez que no puede aplicar los certificados de un grupo de entornos. Por lo general, cada línea incluye campos comoenv_group,secret(y un campo de secreto de confianza cuando la validación de la cadena está activada), un códigoreasony el texto del error unido. Filtra según el valor del códigoreason, que es el identificador estable. No confíes en los otros nombres de campo: Busca en todo el registro en lugar de una ventana reciente: se informa un Secret defectuoso cuando el sidecar lo ve por primera vez (y de nuevo cuando cambia), no en cada actualización.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
Los siguientes códigos de motivo son estables para la versión actual. Si ves un código que no aparece en la lista, comunícate con el equipo de Atención al cliente de Google Cloud.
Excepto porreasonSignificado Acción MCP_MTLS_SECRET_NOT_FOUNDNo existe un Secret al que se hace referencia en el espacio de nombres de Apigee. El texto errorlo nombra y si es el Secret del cliente o de la confianza.Crea el Secret con el nombre exacto (recuerda el sufijo -cacertpara la CA de confianza). El archivo adicional detecta el Secret nuevo por su cuenta.MCP_MTLS_MATERIAL_UNUSABLEEl Secret existe, pero se rechaza su contenido: una clave de datos faltante o vacía, contenido que no es PEM, un certificado y una clave que no se vinculan, un certificado de cliente sin clientAutho un Secret de confianza sin certificado de la AC. El mismo defecto se informa como unApigeeIssue(paso anterior).Corrige el contenido del Secret. Si editas el Secret, se activará un nuevo intento. MCP_MTLS_SECRET_READ_FAILED,MCP_MTLS_SECRET_WATCH_FAILED,MCP_MTLS_SECRET_ACCESS_FAILEDEl archivo adicional no pudo leer ni supervisar los Secrets a través de la API de Kubernetes (el servidor de la API no está disponible o el rol de MCP perdió su permiso secrets). Una líneaMCP_MTLS_SECRET_READ_FAILEDincluye el contexto de reintento, y el archivo adicional vuelve a intentarlo con retirada; las otras dos informan el estado de la observación del Secret del archivo adicional, yMCP_MTLS_SECRET_READER_RECOVEREDse registra cuando se devuelve el acceso.Verifica que el rol de MCP aún otorgue get,listywatchensecrets(consulta Límite de confianza) y que otros componentes del espacio de nombres puedan acceder al servidor de la API. El nombre del rol termina con un sufijo generado, por lo que debes buscarlo conkubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.MCP_MTLS_PUBLISH_FAILEDLos certificados eran válidos, pero no se pudieron escribir en el volumen en memoria del Pod de MCP. El archivo de complemento vuelve a intentarlo con una retirada y registra MCP_MTLS_PUBLISH_RECOVEREDcuando la escritura se realiza correctamente.Esto no se espera en el funcionamiento normal. Si se repite, recopila los registros del archivo adicional y comunícate con la Atención al cliente de Google Cloud. MCP_MTLS_UNKEYABLE_ENV_GROUPEl grupo de entornos tiene mcpMtlsconfigurado, pero su valor de etiquetaenvGroupIdno es un elemento de ruta de acceso válido, por lo que el plano de datos de MCP entrega el grupo a través de TLS unidireccional y una puerta de enlace de entrada en modoMUTUALrechaza sus llamadas a la herramienta. Por lo general, las reglas de etiquetas de Kubernetes impiden estos valores, por lo que un grupo en este estado proviene de un recurso de enrutamiento aplicado directamente al clúster. NingúnApigeeIssueinforma esto.Confirma que el recurso de enrutamiento tenga una etiqueta válida: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Vuelve a ejecutar la actualización deapigee-virtualhostpara el grupo de entornos de modo que el recurso se vuelva a crear a partir del gráfico.MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATIONEl grupo de entornos establece disableChainValidation: trueydisableSanValidation: falsejuntos. La coincidencia de SAN se produce dentro de la validación que configura el conjunto de validación de la cadena, por lo que, con la validación de la cadena desactivada, no hay nada con lo que coincidir y se ignora el parámetro de configuración. El gráfico rechaza esta vinculación, por lo que un grupo en este estado proviene de un recurso personalizado aplicado directamente al clúster.Quita disableSanValidationdel bloquemcpMtlsdel grupo de entornos o vuelve a establecerdisableChainValidationenfalsey proporciona una CA de confianza (consultadisableSanValidation).MCP_MTLS_CONFLICTING_CONFIGDos recursos de enrutamiento en el mismo grupo de entornos llevan diferentes bloques mcpMtls, por lo que el plano de datos de MCP usa el que depende del orden en que se procesan las rutas. El grupo puede terminar presentando un certificado de cliente diferente del que configuraste, y nada en sentido descendente registra qué bloque ganó.Vuelve a ejecutar la actualización de apigee-virtualhostpara el grupo de entornos y, luego, confirma que los bloques coincidan con el comandoget apigeeroutesen el paso 1. Cada ruta de un grupo deriva de la entradavirtualhosts[]única de ese grupo, por lo que un desacuerdo significa que los recursos se aplicaron directamente al clúster o que una actualización anterior se propagó solo de forma parcial.MCP_MTLS_UNKEYABLE_ENV_GROUP, que reduce el grupo de entornos a TLS unidireccional, el grupo de entornos sigue usando los últimos certificados que el archivo de tareas de apoyo cargó correctamente. Si nunca cargó ninguno (primera habilitación), las llamadas de la herramienta de MCP a ese grupo de entornos fallarán hasta que se solucione el problema; los demás grupos de entornos no se verán afectados. No es necesario reiniciar el Pod después de la corrección.Los códigos
MCP_MTLS_restantes no requieren ninguna acción por sí mismos.MCP_MTLS_CHAIN_VALIDATION_DISABLEDyMCP_MTLS_SAN_VALIDATION_DISABLEDregistran que un grupo de entornos desactivó una validación, por lo que la elección se puede encontrar en una flota.MCP_MTLS_MATERIAL_REMOVEDes la limpieza de rutina después de que un grupo se inhabilita, yMCP_MTLS_COLLECTION_FAILEDsignifica que la limpieza no se completó y los archivos de certificado del grupo aún están en el Pod; la próxima actualización vuelve a intentar la limpieza. - Si el clúster no informa ningún problema y los registros de sidecar están limpios, pero las llamadas a la herramienta al
grupo de entornos siguen fallando, uno de los lados rechaza el protocolo de enlace:
- La puerta de enlace de entrada rechaza el certificado de cliente cuando su entidad emisora no está en la
AC en la que confía la puerta de enlace de entrada para ese grupo de entornos
(
virtualhosts[].caCertPathoINGRESS_SECRET_NAME-cacert). Verifica conopenssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE. - El plano de datos de MCP rechaza el certificado de la puerta de enlace de entrada cuando no se encadena
a la AC en
mcpMtls.caCertPathoMCP_CLIENT_SECRET_NAME-cacert, o cuando sus nombres alternativos de sujeto no incluyen el alias de host del grupo de entornos. Verifica conopenssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILEe inspecciona los SAN conopenssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName. Se recomienda volver a emitir el certificado de la puerta de enlace de entrada para que cubra el alias del host. Solo si eso no es posible, establecemcpMtls.disableSanValidation: truepara ese grupo de entornos, lo que impide que el plano de datos de MCP verifique el nombre en el certificado de la puerta de enlace de entrada.
- La puerta de enlace de entrada rechaza el certificado de cliente cuando su entidad emisora no está en la
AC en la que confía la puerta de enlace de entrada para ese grupo de entornos
(
Casos de asistencia
Si abres un caso de asistencia que involucra el plano de datos de MCP de Apigee Hybrid, adjunta el siguiente resultado para acelerar el diagnóstico:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server --all-containers --tail=1000kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-serverkubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wideykubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.- Resultado reciente de
overrides.yamlyhelm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE(en el queAPIGEE_ORG_RELEASE_NAMEes el nombre de la versión de Helm para el gráficoapigee-org; búscalo conhelm list -n APIGEE_NAMESPACE | grep apigee-org). Antes de compartiroverrides.yaml, oculta el material secreto, incluido lo siguiente:- Cualquier clave de cuenta de servicio intercalada en
gcp.workloadIdentity,envs[].serviceAccountPathsomcpServer.serviceAccountPath. - Cualquier certificado TLS o clave privada en
virtualhosts. - Los campos de contraseña de
cassandra.auth - Son las credenciales intercaladas que tus anulaciones pasan al operador.
- Cualquier clave de cuenta de servicio intercalada en
- El comando
curlcompleto y la respuesta que reproduce el problema.
No se puede cambiar el estilo de la API a MCP en el concentrador de APIs
Si ya existe un recurso de API con operaciones de API en el centro de APIs de Apigee, no puedes cambiar el atributo Estilo de API de ese recurso a MCP. Para registrar una API en el centro de APIs de Apigee como una API de MCP, debes seleccionar el estilo MCP cuando registres la API por primera vez o asegurarte de que no haya operaciones presentes en el recurso de la API antes de cambiar el estilo a MCP.
Si tienes algún otro problema, consulta Cómo usar la depuración para obtener información detallada sobre cómo usar la herramienta de depuración en la consola de Google Cloud para analizar las solicitudes y respuestas hacia y desde tu proxy de descubrimiento de MCP.