Certificado do cliente mTLS do MCP inválido

Esta página se aplica à Apigee híbrida, mas não à Apigee.

Não há documentação equivalente da Apigee Edge para esse tópico.

Sintoma

Um ApigeeIssue com Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID é exibido ao visualizar recursos no namespace apigee.

Mensagens de erro

Depois de executar kubectl -n apigee get apigeeissues, um erro como este é exibido:

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 possíveis

A tabela a seguir lista as possíveis causas desse problema:

Causa Descrição
A entrada ou o secret do certificado do cliente mTLS do MCP está ausente O secret nomeado por mcpMtls não existe ou não tem uma entrada cert ou key utilizável.
O certificado do cliente ou a chave mTLS do MCP está incorreto A entrada cert não está codificada em PEM ou a entrada key não é a chave privada correspondente.
O certificado do cliente mTLS do MCP omite o uso de chave estendido clientAuth O certificado é analisado, mas o uso de chave estendido não inclui clientAuth.

Causa: o secret ou a entrada do certificado do cliente mTLS do MCP está ausente

O secret do Kubernetes que deveria conter o certificado do cliente mTLS do MCP não existe no namespace apigee ou existe sem uma entrada cert não vazia ou sem uma entrada key. O plano de dados do MCP não tem um certificado do cliente para apresentar a esse grupo de ambientes. Portanto, as chamadas de ferramenta do MCP para o grupo falham no handshake de TLS.

Diagnóstico

Execute este comando:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

A saída será parecida com esta:

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

O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:

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

Resolução

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.

Arquivos de certificado

Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath, caCertPath), o gráfico do host virtual cria e gerencia as secrets do conteúdo do arquivo.

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. Verifique se o secret existe e tem as duas entradas, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em Spec.Details. A seção Data precisa listar cert e key:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    Se o secret estiver ausente ou não tiver uma entrada, verifique se os arquivos referenciados por mcpMtls.sslCertPath e mcpMtls.sslKeyPath existem e não estão vazios. A próxima etapa restaura o secret usando esses dados.

  2. Faça upgrade do host virtual para que o gráfico reescreva o secret:

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

Secrets do Kubernetes

Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP lê os valores do certificado diretamente dos secrets que você criou, e as atualizações são aplicadas automaticamente. Não é necessário usar helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Confirme se o secret existe e tem as duas entradas, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em Spec.Details. A seção Data precisa listar cert e key. Verifique se o nome em mcpMtls.sslSecret corresponde ao secret que você criou e se o secret está no namespace 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 não verifica se os secrets existem. Somente helm install e helm upgrade fazem isso. Portanto, uma execução limpa de helm template não é evidência de que esse secret está presente.

  2. Crie ou atualize o secret com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em Spec.Details e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele:

    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 -

O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima verificação.

Causa: o certificado do cliente ou a chave mTLS do MCP está incorreto

A entrada cert não contém um certificado X.509 codificado em PEM ou a entrada key não está codificada em PEM ou não é a chave privada desse certificado. O plano de dados do MCP não pode carregar o par.

Diagnóstico

Execute este comando:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

A saída será parecida com esta:

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

O conteúdo de Spec.Details nomeia o secret, o ApigeeRouteConfig e o que está errado. Exemplo:

  • entry holds no PEM encoded certificate: a entrada cert não é PEM.
  • tls: failed to find any PEM data in key input: a entrada key não é PEM.
  • tls: private key does not match public key: as entradas cert e key não estão pareadas.
  • tls: failed to parse private key: não é possível analisar a chave, geralmente porque ela está criptografada. A entrada key precisa ser uma chave privada PEM não criptografada.

Resolução

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.

Arquivos de certificado

Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath, caCertPath), o gráfico do host virtual cria e gerencia as secrets do conteúdo do arquivo.

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. Valide o arquivo de certificado e o arquivo de chave referenciados por mcpMtls.sslCertPath e mcpMtls.sslKeyPath e corrija-os, se necessário. O certificado precisa conter as linhas de início e fim, e a chave precisa ser a chave privada dele. Exemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Faça upgrade do host virtual para que o gráfico reescreva o secret:

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

Secrets do Kubernetes

Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP lê os valores do certificado diretamente dos secrets que você criou, e as atualizações são aplicadas automaticamente. Não é necessário usar helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Valide o arquivo de certificado (MCP_CLIENT_CERT_FILE) e o arquivo de chave (MCP_CLIENT_KEY_FILE) que você armazena nas entradas cert e key do secret e corrija-os, se necessário. O certificado precisa conter as linhas de início e fim, e a chave precisa ser a chave privada dele. Exemplo:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Atualize o secret no local com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em Spec.Details, e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele:

    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 -

O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima verificação.

Causa: o certificado do cliente mTLS do MCP omite o uso de chave estendido clientAuth

O certificado está bem formado e é pareado com a chave, mas o uso de chave estendido (EKU, na sigla em inglês) não inclui clientAuth. Portanto, ele não pode ser usado para autenticação de cliente, e o plano de dados do MCP não o apresenta. Isso é comum quando um certificado de servidor ou um certificado de um perfil de CA público que não emite mais clientAuth é reutilizado.

Diagnóstico

Execute este comando:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

A saída será parecida com esta:

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

O conteúdo de Spec.Details nomeia o secret e o ApigeeRouteConfig e lista os usos de chave estendidos que o certificado carrega.

Resolução

  1. Use kubectl describe para exibir o nome do secret do Kubernetes e o ApigeeRouteConfig ao qual o problema pertence:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Substitua ISSUE_NAME pelo nome do problema, por exemplo, mcp-client-cert-invalid-my-org-my-virtualhost.

    Neste exemplo, o ApigeeRouteConfig my-org-my-virtualhost referencia o secret my-org-my-virtualhost-mcp.

  2. Determine o nome do virtualhost no ApigeeRouteConfig.

    O nome do ApigeeRouteConfig está no formato: <Apigee organization>-<virtualhost name>.

    Neste exemplo, my-org é a organização da Apigee, e o nome do virtualhost é my-virtualhost.

  3. Encontre o host virtual correspondente no overrides.yaml e verifique qual formulário o bloco mcpMtls usa (consulte Configurar mTLS entre o plano de dados do MCP e o gateway de entrada). Selecione a guia correspondente e siga as etapas nela.

Arquivos de certificado

Quando você usa caminhos de arquivo (sslCertPath, sslKeyPath, caCertPath), o gráfico do host virtual cria e gerencia as secrets do conteúdo do arquivo.

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. Emita novamente o certificado do cliente da sua CA particular com um perfil que inclua o uso de chave estendido clientAuth. Confirme, em que MCP_CLIENT_CERT_FILE é o certificado reemitido, e substitua os arquivos referenciados por mcpMtls.sslCertPath e mcpMtls.sslKeyPath:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Faça upgrade do host virtual para que o gráfico reescreva o secret:

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

Secrets do Kubernetes

Quando você usa uma referência de secret do Kubernetes (sslSecret), o plano de dados do MCP lê os valores do certificado diretamente dos secrets que você criou, e as atualizações são aplicadas automaticamente. Não é necessário usar helm upgrade.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Emita novamente o certificado do cliente da sua CA particular com um perfil que inclua o uso de chave estendido clientAuth. Confirme isso antes de atualizar o secret, em que MCP_CLIENT_CERT_FILE é o certificado reemitido:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Atualize o secret no local com o certificado e a chave privada dele, em que MCP_CLIENT_SECRET_NAME é o secret nomeado em Spec.Details, e MCP_CLIENT_CERT_FILE e MCP_CLIENT_KEY_FILE são o certificado e a chave privada dele:

    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 -

O plano de dados do MCP seleciona o secret corrigido na próxima atualização periódica, normalmente em alguns minutos, sem uma reinicialização do pod, e o ApigeeIssue é retirado na próxima verificação.

É necessário coletar informações de diagnóstico

Se o problema persistir mesmo depois de seguir as instruções acima, colete as seguintes informações de diagnóstico e entre em contato com o Google Cloud Customer Care:

  1. O ID do projeto do Google Cloud .
  2. O nome da organização da Apigee híbrida.
  3. O campo Spec.Details do ApigeeIssue.
  4. (Opcional) O certificado no arquivo referenciado por mcpMtls.sslCertPath ou na entrada cert do secret para o host virtual afetado.