Soluciona problemas de implementaciones de 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 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.

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.

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-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-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 info que indica que no hay configuración de MCP desde el plano de control:
    {"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"}
    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.
  • Línea error con un contador consecutive_failures:
    {"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>"}
    Los registros de sidecar son JSON estructurados. Cuando veas "level":"error" con un contador consecutive_failures en 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-watcher no está en la lista watcher_identities del recurso controlPlaneAccess de 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.com o storage.googleapis.com está 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-watcher no 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.

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.

  1. Confirma que el operador aceptó el campo. El recurso de enrutamiento del grupo de entornos debe llevar el bloque mcpMtls:
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    Una segunda columna vacía, varios minutos después de la actualización de apigee-virtualhost, suele significar que las definiciones de recursos personalizados de Apigee en el clúster son anteriores a 1.17.4 y no declaran mcpMtls, por lo que el servidor de la API descartó el campo. (Con menos frecuencia, el gráfico apigee-org que proporciona la imagen del observador no se actualizó a 1.17.4). Esto sucede cuando se ejecutó una actualización helm upgrade para 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 modo MUTUAL lo rechaza. Los mismos CRD obsoletos también evitan que se informen los problemas de AIS_MCP_MTLS_* en el siguiente paso. Verifica y corrige con lo siguiente:
    kubectl 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
    Ejecuta kubectl apply desde el directorio de gráficos de Helm y, luego, vuelve a ejecutar la actualización de apigee-virtualhost para el grupo de entornos.
  2. Verifica si hay problemas con los certificados que informa el clúster. El observador analiza los Secrets configurados y crea un ApigeeIssue para cada problema:
    kubectl -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
    El campo Spec.Details nombra el Secret y el ApigeeRouteConfig (llamado ORG_NAME-ENV_GROUP_NAME) al que pertenece el problema, y el defecto específico.
    Motivo Gravedad Significado Corregir
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR El Secret del certificado de cliente no existe (secret not found), falta una entrada cert o key, 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 omite clientAuth. 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 con clientAuth.
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY WARNING en un plazo de 14 días antes del vencimiento; ERROR después El 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_INVALID ERROR El Secret -cacert no existe (secret not found; con sslSecret, lo creas tú), falta su entrada cacert, 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_EXPIRY WARNING en un plazo de 14 días antes del vencimiento; ERROR después Un certificado de la AC en el Secret -cacert está 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 -cacert antes de que venza, junto con el certificado propio de la puerta de enlace de entrada si también se vuelve a emitir.
    Los problemas se retiran automáticamente en el siguiente análisis después de que se corrige el Secret.
  3. Lee los mensajes de mTLS del archivo adicional. El contenedor apigee-mcp-server-config registra una línea error cada vez que no puede aplicar los certificados de un grupo de entornos. Por lo general, cada línea incluye campos como env_group, secret (y un campo de secreto de confianza cuando la validación de la cadena está activada), un código reason y el texto del error unido. Filtra según el valor del código reason, que es el identificador estable. No confíes en los otros nombres de campo:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    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.

    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.

    reason Significado Acción
    MCP_MTLS_SECRET_NOT_FOUND No existe un Secret al que se hace referencia en el espacio de nombres de Apigee. El texto error lo nombra y si es el Secret del cliente o de la confianza. Crea el Secret con el nombre exacto (recuerda el sufijo -cacert para la CA de confianza). El archivo adicional detecta el Secret nuevo por su cuenta.
    MCP_MTLS_MATERIAL_UNUSABLE El 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 clientAuth o un Secret de confianza sin certificado de la AC. El mismo defecto se informa como un ApigeeIssue (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_FAILED El 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ínea MCP_MTLS_SECRET_READ_FAILED incluye 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, y MCP_MTLS_SECRET_READER_RECOVERED se registra cuando se devuelve el acceso. Verifica que el rol de MCP aún otorgue get, list y watch en secrets (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 con kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.
    MCP_MTLS_PUBLISH_FAILED Los 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_RECOVERED cuando 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_GROUP El grupo de entornos tiene mcpMtls configurado, pero su valor de etiqueta envGroupId no 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 modo MUTUAL rechaza 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ún ApigeeIssue informa 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 de apigee-virtualhost para el grupo de entornos de modo que el recurso se vuelva a crear a partir del gráfico.
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION El grupo de entornos establece disableChainValidation: true y disableSanValidation: false juntos. 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 disableSanValidation del bloque mcpMtls del grupo de entornos o vuelve a establecer disableChainValidation en false y proporciona una CA de confianza (consulta disableSanValidation).
    MCP_MTLS_CONFLICTING_CONFIG Dos 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-virtualhost para el grupo de entornos y, luego, confirma que los bloques coincidan con el comando get apigeeroutes en el paso 1. Cada ruta de un grupo deriva de la entrada virtualhosts[] ú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.
    Excepto por 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_DISABLED y MCP_MTLS_SAN_VALIDATION_DISABLED registran que un grupo de entornos desactivó una validación, por lo que la elección se puede encontrar en una flota. MCP_MTLS_MATERIAL_REMOVED es la limpieza de rutina después de que un grupo se inhabilita, y MCP_MTLS_COLLECTION_FAILED significa 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.

  4. 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[].caCertPath o INGRESS_SECRET_NAME-cacert). Verifica con openssl 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.caCertPath o MCP_CLIENT_SECRET_NAME-cacert, o cuando sus nombres alternativos de sujeto no incluyen el alias de host del grupo de entornos. Verifica con openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE e inspecciona los SAN con openssl 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, establece mcpMtls.disableSanValidation: true para 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.

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=1000
  • kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-server
  • kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wide y kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.
  • Resultado reciente de overrides.yaml y helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE (en el que APIGEE_ORG_RELEASE_NAME es el nombre de la versión de Helm para el gráfico apigee-org; búscalo con helm list -n APIGEE_NAMESPACE | grep apigee-org). Antes de compartir overrides.yaml, oculta el material secreto, incluido lo siguiente:
    • Cualquier clave de cuenta de servicio intercalada en gcp.workloadIdentity, envs[].serviceAccountPaths o mcpServer.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.
  • El comando curl completo 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.