El certificado de cliente de mTLS de MCP no es válido

Esta página se aplica a Apigee Hybrid, pero no a Apigee.

No hay documentación de Apigee Edge equivalente para este tema.

Síntoma

Se muestra un ApigeeIssue con Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID cuando se visualizan los recursos en el espacio de nombres apigee.

Mensajes de error

Después de ejecutar kubectl -n apigee get apigeeissues, se muestra un error como el siguiente:

NAME                                            SEVERITY   REASON                             DOCUMENTATION                                                                                  AGE
mcp-client-cert-invalid-my-org-my-virtualhost   ERROR      AIS_MCP_MTLS_CLIENT_CERT_INVALID   https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID   5h18m

Causas posibles

En la siguiente tabla, se enumeran las posibles causas de este problema:

Causa Descripción
Falta el secreto o la entrada del certificado de cliente de mTLS de MCP El secreto que se indica en mcpMtls no existe o no tiene una entrada cert o key que se pueda usar.
El certificado de cliente o la clave de mTLS de MCP tiene un formato incorrecto La entrada cert no está codificada con PEM o la entrada key no es la clave privada coincidente.
El certificado de cliente de mTLS de MCP omite el uso de clave extendido clientAuth El certificado se analiza, pero su uso de clave extendido no incluye clientAuth.

Causa: Falta el secreto o la entrada del certificado de cliente de mTLS de MCP

El Secret de Kubernetes que debería contener el certificado de cliente de mTLS de MCP no existe en el espacio de nombres apigee, o existe sin una entrada cert no vacía o sin una entrada key. El plano de datos de MCP no tiene un certificado de cliente para presentar en este grupo de entornos, por lo que las llamadas a la herramienta de MCP al grupo fallan en el protocolo de enlace TLS.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found

El contenido de Spec.Details nombra el Secret, el ApigeeRouteConfig y lo que está mal. Por ejemplo:

  • secret not found
  • secret has no usable "cert" entry
  • secret has no "key" entry

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Verifica si el Secret existe y tiene ambas entradas, en las que MCP_CLIENT_SECRET_NAME es el Secret que se menciona en Spec.Details. La sección Data debe enumerar cert y key:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    Si falta el secreto o no tiene una entrada, asegúrate de que los archivos a los que hacen referencia mcpMtls.sslCertPath y mcpMtls.sslKeyPath existan y no estén vacíos. En el siguiente paso, se restablece el secreto a partir de ellos.

  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Confirma que el Secret exista y tenga ambas entradas, en las que MCP_CLIENT_SECRET_NAME es el Secret que se menciona en Spec.Details. La sección Data debe incluir cert y key. Verifica que el nombre en mcpMtls.sslSecret coincida con el Secret que creaste y que el Secret esté en el espacio de nombres apigee:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
    kubectl get secret -A --field-selector metadata.name=MCP_CLIENT_SECRET_NAME   # if the first command finds nothing

    helm template no verifica que los Secrets existan; solo lo hacen helm install y helm upgrade, por lo que una ejecución limpia de helm template no es evidencia de que este Secret esté presente.

  2. Crea o actualiza el Secret con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se nombra en Spec.Details y MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Causa: El certificado o la clave de cliente de mTLS de MCP tiene un formato incorrecto

La entrada cert no contiene un certificado X.509 codificado con PEM, o la entrada key no está codificada con PEM o no es la clave privada de ese certificado. El plano de datos de MCP no puede cargar el par.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key

El contenido de Spec.Details nombra el Secret, el ApigeeRouteConfig y lo que está mal. Por ejemplo:

  • entry holds no PEM encoded certificate: La entrada cert no es PEM.
  • tls: failed to find any PEM data in key input: La entrada key no es PEM.
  • tls: private key does not match public key: Las entradas cert y key no se vinculan.
  • tls: failed to parse private key: No se puede analizar la clave, por lo general, porque está encriptada. La entrada key debe ser una clave privada PEM sin encriptar.

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Valida el archivo de certificado y el archivo de clave a los que hacen referencia mcpMtls.sslCertPath y mcpMtls.sslKeyPath, y corrígelos si es necesario. El certificado debe contener las líneas de certificado iniciales y finales, y la clave debe ser la clave privada para él. Por ejemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Valida el archivo de certificado (MCP_CLIENT_CERT_FILE) y el archivo de clave (MCP_CLIENT_KEY_FILE) que almacenas en las entradas cert y key del Secret, y corrígelos si es necesario. El certificado debe contener las líneas de certificado iniciales y finales, y la clave debe ser la clave privada para él. Por ejemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Actualiza el Secret en su lugar con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se indica en Spec.Details y MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Causa: El certificado de cliente de mTLS de MCP omite el uso de clave extendido clientAuth

El certificado tiene un formato correcto y se vincula con su clave, pero su uso extendido de la clave (EKU) no incluye clientAuth, por lo que no se puede usar para la autenticación del cliente y el plano de datos de MCP no lo presenta. Esto es común cuando se reutiliza un certificado de servidor o un certificado de un perfil de CA público que ya no emite clientAuth.

Diagnóstico

Ejecuta el comando siguiente:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

El resultado debería ser similar al siguiente:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth

El contenido de Spec.Details nombra el secreto y el ApigeeRouteConfig, y enumera los usos de claves extendidos que lleva el certificado.

Solución

  1. Usa kubectl describe para mostrar el nombre del Secret de Kubernetes y ApigeeRouteConfig al que pertenece el problema:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Reemplaza ISSUE_NAME por el nombre del problema, por ejemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    En este ejemplo, ApigeeRouteConfig my-org-my-virtualhost hace referencia al Secret my-org-my-virtualhost-mcp.

  2. Determina el nombre virtualhost de ApigeeRouteConfig.

    El nombre de ApigeeRouteConfig tiene el siguiente formato: <Apigee organization>-<virtualhost name>.

    En este ejemplo, my-org es la organización de Apigee y el nombre del host virtual es my-virtualhost.

  3. Busca el host virtual correspondiente en tu overrides.yaml y verifica qué formato usa su bloque mcpMtls (consulta Configura mTLS entre el plano de datos de MCP y la puerta de enlace de entrada). Selecciona la pestaña que coincida y sigue los pasos que se indican en ella.

Archivos de certificados

Cuando usas rutas de acceso de archivos (sslCertPath, sslKeyPath, caCertPath), el gráfico de host virtual crea y administra los secretos a partir del contenido del archivo.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Vuelve a emitir el certificado de cliente desde tu CA privada con un perfil que incluya el uso de clave extendido clientAuth. Confírmalo, donde MCP_CLIENT_CERT_FILE es el certificado que se volvió a emitir y, luego, reemplaza los archivos a los que hacen referencia mcpMtls.sslCertPath y mcpMtls.sslKeyPath:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Actualiza el host virtual para que el gráfico reescriba el Secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secretos de Kubernetes

Cuando usas una referencia de Secret de Kubernetes (sslSecret), el plano de datos de MCP lee los valores del certificado directamente de los Secrets que creaste, y las actualizaciones se aplican automáticamente. No se necesita helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Vuelve a emitir el certificado de cliente desde tu CA privada con un perfil que incluya el uso de clave extendido clientAuth. Confírmalo antes de actualizar el secreto, donde MCP_CLIENT_CERT_FILE es el certificado que se volvió a emitir:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Actualiza el Secret en su lugar con el certificado y su clave privada juntos, en el que MCP_CLIENT_SECRET_NAME es el Secret que se indica en Spec.Details y MCP_CLIENT_CERT_FILE y MCP_CLIENT_KEY_FILE son el certificado y su clave privada:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

El plano de datos de MCP recoge el secreto corregido en su próxima actualización periódica, por lo general, en unos minutos, sin reiniciar el Pod, y el ApigeeIssue se retira en el siguiente análisis.

Se debe recopilar información de diagnóstico

Si el problema persiste incluso después de seguir las instrucciones anteriores, recopila la siguiente información de diagnóstico y, luego, comunícate con la Atención al cliente de Google Cloud:

  1. Es el ID del proyecto de Google Cloud .
  2. El nombre de la organización de Apigee hybrid.
  3. El campo Spec.Details de ApigeeIssue.
  4. (Opcional) El certificado en el archivo al que hace referencia mcpMtls.sslCertPath o en la entrada cert del secreto para el host virtual afectado.