Resolver problemas de implantações do MCP na Apigee

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como solucionar problemas com a implantação de proxies de descoberta do MCP. Use esta página para entender o ciclo de vida de provisionamento assíncrono das implantações do MCP, resolver códigos do erro e verificar a conectividade do ambiente de execução.

Noções básicas sobre a implantação do MCP

A implantação de um proxy de descoberta do MCP é um processo assíncrono de várias etapas que garante que a configuração seja totalmente propagada pela infraestrutura da Apigee e do Google Cloud antes que a implantação do proxy seja concluída.

Enquanto essas etapas de provisionamento downstream estão ocorrendo, a UI mostra o proxy com o status Provisionamento. Quando o processo for concluído, o status vai mudar para Implantado. Esse status confirma que todos os componentes downstream estão totalmente provisionados e que o proxy está pronto para processar o tráfego.

Solução de problemas

As seções a seguir descrevem erros e problemas conhecidos que podem ser encontrados ao usar o MCP na Apigee.

Problema: um back-end lê um argumento de ferramenta de um local de solicitação, como a string de consulta, um cabeçalho ou um cookie, mas a especificação OpenAPI declara o parâmetro in em um local diferente. Assim, o argumento chega em outro lugar na solicitação de back-end. A chamada falha ou se comporta como se o argumento estivesse ausente.

Sintomas: a solicitação tools/call é bem-sucedida na camada do MCP, e o cliente do MCP fornece o argumento, mas o back-end responde como se o valor estivesse ausente. Por exemplo, um 400 para um valor obrigatório ou um padrão sendo aplicado no lugar do valor enviado.

Causa: o parâmetro é declarado como in: header ou in: cookie na especificação OpenAPI. Portanto, a Apigee envia o valor como um cabeçalho da solicitação ou no cabeçalho Cookie, em vez de na string de consulta. Um back-end que lê o valor apenas da string de consulta não o vê. Consulte Posicionamento do argumento da ferramenta na solicitação de back-end.

Resolução: decida onde o valor pertence e faça com que a especificação e o back-end concordem:

  • Para manter o valor na string de consulta, declare o parâmetro in: query.
  • Para enviá-lo como um cabeçalho ou cookie, deixe a declaração como está e leia o valor desse local no back-end.

Problema: um cookie que chega na solicitação HTTP feita pelo cliente do MCP, como um cookie de sessão de um cliente baseado em navegador, deixa de chegar ao back-end em algumas chamadas de ferramenta.

Sintomas: o back-end se comporta como se o autor da chamada não estivesse autenticado ou não estivesse na sessão, e o comportamento é inconsistente: a mesma operação funciona em algumas chamadas e não em outras.

Causa: a operação declara um ou mais parâmetros in: cookie, e as chamadas afetadas forneceram pelo menos um deles. O cabeçalho Cookie é reescrito como um todo, em vez de ser anexado. Portanto, nessas chamadas, ele carrega apenas os parâmetros de cookie declarados, e todos os outros cookies são descartados. As chamadas que não forneceram nenhum dos parâmetros de cookie transmitem o cabeçalho sem alterações, por isso apenas algumas chamadas falham. Consulte Cookies na solicitação para seu back-end.

Resolução: declare todos os cookies necessários para o back-end como um parâmetro in: cookie em cada operação que precisa deles. Assim, o valor será sempre fornecido pela chamada de ferramenta, em vez de ser herdado da solicitação do cliente. Não há uma configuração que preserve um cookie não declarado.

Códigos de status de resposta de erro para chamadas de ferramentas e metadados

Os endpoints do MCP da Apigee retornam códigos de status HTTP que seguem a especificação do Protocolo de Contexto de Modelo (MCP) e os padrões OAuth relacionados. Entender esse comportamento ajuda a lidar corretamente com erros no seu cliente MCP ou agente de IA.

A tabela a seguir resume os códigos de status retornados pelos endpoints do MCP da Apigee:

Cenário Código de status HTTP Corpo da resposta
A execução de uma ferramenta falha em tools/call (por exemplo, a API de back-end retorna um erro 4xx ou 5xx, como um erro de validação ou um campo obrigatório ausente). 200 OK Um CallToolResult com result.isError definido como true e os detalhes do erro em content. Isso permite que o cliente do MCP e o agente de LLM leiam o erro e se recuperem (por exemplo, solicitando novamente a entrada ausente e tentando de novo) em vez de encerrar a sessão.
Os metadados de recursos protegidos (PRM, na sigla em inglês) do OAuth não estão configurados ou não podem ser encontrados em /.well-known/oauth-protected-resource/mcp. 404 Not Found Indica que não há metadados de recursos sem proteção disponíveis no local solicitado.
O token de acesso está ausente, é inválido ou expirou. 401 Unauthorized Inclui um desafio WWW-Authenticate para impulsionar o fluxo de descoberta do OAuth.
O token de acesso tem escopo insuficiente. 403 Forbidden Inclui um desafio WWW-Authenticate para impulsionar o fluxo de autorização de upgrade.

Exemplo: corpo da resposta de erro de execução da ferramenta

Quando uma chamada de ferramenta falha, o MCP da Apigee retorna HTTP 200 OK e informa a falha no objeto JSON-RPC result, com isError definido como true. O erro original retornado pelo back-end é preservado: o corpo da resposta do back-end é colocado literalmente (como uma string) em result.content[].text. Por exemplo, se o back-end retornar HTTP 404 com o corpo {"error":"User 42 not found"}, a resposta do MCP será:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

O id corresponde ao id da sua solicitação tools/call. Se o back-end não retornar um corpo de resposta, text vai conter um resumo gerado, como Operation failed (HTTP 500)..

Seu cliente MCP precisa inspecionar result.isError (não o código de status HTTP) para detectar uma chamada de ferramenta com falha. Se o código do cliente espera especificamente um status HTTP 4xx ou 5xx para sinalizar um erro de execução da ferramenta, ele não detecta o erro, porque a resposta é HTTP 200 OK. Atualize esses clientes para ler result.isError e a matriz content.

Os erros no nível do protocolo (por exemplo, uma solicitação JSON-RPC malformada) são diferentes dos erros de execução da ferramenta: eles continuam sendo retornados no objeto JSON-RPC error (por exemplo, {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) em vez de em result.isError.

Recomendação: os clientes MCP que seguem os padrões lidam com esses códigos de status usando a lógica padrão, então não é preciso fazer mudanças. Se você adicionou uma solução alternativa do lado do cliente para lidar com códigos de status não padrão, por exemplo, analisando um corpo de resposta não 2xx para erros tools/call ou tratando uma resposta 500 do endpoint do PRM como "metadados não configurados", recomendamos remover essa solução alternativa. Caso contrário, o cliente poderá continuar usando uma lógica de processamento obsoleta em vez de processar os códigos de status corrigidos normalmente.

Política de CORS para chamadas de MCP baseadas em navegador

Uma política de Compartilhamento de recursos entre origens (CORS) é necessária quando as chamadas do MCP da Apigee são feitas diretamente de um navegador (por exemplo, quando o inspetor do MCP usa a configuração "Direto" em vez de "Via proxy"). O modelo de proxy de descoberta do MCP inclui a política de CORS da Apigee no PreFlow de solicitação do endpoint de proxy do pacote de proxy por padrão para permitir chamadas baseadas em navegador.

Se você tiver problemas relacionados ao CORS ao fazer chamadas diretamente de um navegador, talvez seja necessário ajustar as configurações da política de CORS no PreFlow de solicitação do endpoint de proxy do pacote de proxy de descoberta do MCP.

Erro de análise de JSON ao enviar solicitação para o endpoint do MCP

Talvez você receba uma mensagem de erro semelhante a esta (ou com um código do erro e uma mensagem de erro diferentes) ao enviar uma solicitação para o endpoint do MCP:

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

Nesse caso, recomendamos confirmar as seguintes informações:

  • Você inseriu o URL correto do endpoint do MCP.
  • Sua solicitação está formatada corretamente.
  • Você está acessando um método compatível.
  • Você ativou e configurou o proxy de descoberta do MCP em uma região com disponibilidade. Para uma lista de regiões que podem ter limites de capacidade, consulte falhas de implantação.

Falhas na implantação

Se a implantação do proxy de descoberta do MCP falhar com um status Falha na UI, verifique a mensagem de erro para mais detalhes. As falhas comuns incluem:

  • Falha na configuração de rede ou Esquema não compatível no OAS: esses erros geralmente indicam um problema com a especificação OpenAPI. Verifique se a especificação é válida e usa uma versão compatível.
  • Limites de capacidade da região (somente Apigee): se você receber um erro relacionado à falha de provisionamento do balanceador de carga ou se o status de provisionamento nunca mudar para Implantado, isso pode ser devido a limites temporários de capacidade de infraestrutura em uma das seguintes regiões:
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    Para resolver o erro, tente implantar o proxy em um ambiente em uma região diferente. Esse modo de falha não se aplica à Apigee híbrida, em que a infraestrutura do ambiente de execução é seu próprio cluster.

  • MCP não ativado no cluster (somente na Apigee híbrida): se a implantação do proxy do MCP permanecer no status Provisionamento indefinidamente e nunca chegar a Implantado, verifique se o MCP está ativado no cluster. Consulte Diagnóstico do lado do cluster abaixo.

Diagnóstico do lado do cluster (somente Apigee híbrida)

Como o plano de dados do MCP da Apigee híbrida é executado no seu próprio cluster do Kubernetes, os modos de falha no cluster são diagnosticados com kubectl no cluster. Siga a lista de verificação de diagnóstico abaixo.

Etapa 1: verificar se o MCP está ativado no cluster

O MCP é implantado como um recurso personalizado ApigeeDeployment (gerenciado pelo operador da Apigee), não como um Deployment do Kubernetes simples. Verifique o MCP ApigeeDeployment:

kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server

Saída esperada (os nomes dos recursos incluem um sufixo derivado da organização, mostrado aqui como ORG_CR_SUFFIX):

NAME                                     STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX       running                 1h

Se o comando retornar No resources found in APIGEE_NAMESPACE namespace., o MCP não está ativado. Volte para Ativar o MCP na Apigee híbrida e verifique se enableMcpServer: true está definido como uma chave de nível superior no overrides.yaml e se você fez upgrade da versão do Helm apigee-operator antes da versão apigee-org. Consulte as etapas 3 e 4 do procedimento de ativação para ver os comandos helm corretos.

Etapa 2: verificar se os pods do MCP estão em execução

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server

Saída esperada (os sufixos do pod serão 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

Os nomes dos pods seguem o modelo apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH, em que REV é a revisão de quatro dígitos da versão híbrida (por exemplo, 1170 para a versão híbrida 1.17.0) e POD_HASH é um sufixo alfanumérico de oito caracteres que é diferente para cada pod.

Cada pod precisa mostrar 2/2 na coluna READY e Running na coluna STATUS. Se os pods não forem Running, kubectl -n APIGEE_NAMESPACE describe pod POD_NAME vai mostrar o motivo. As causas comuns são falhas de extração de imagem (verifique a saída do cluster para o registro de imagem configurado no overrides.yaml) e CPU ou margem de memória insuficiente (aumente mcpServer.resources.requests em overrides.yaml).

Etapa 3: verificar o status de extração da configuração do arquivo secundário

O contêiner secundário apigee-mcp-server-config em cada pod do MCP extrai periodicamente a configuração do MCP do plano de controle da Apigee. Cada extração recupera a referência de configuração atual de apigee.googleapis.com e, em seguida, busca o pacote de configuração referenciado no Cloud Storage. O plano de dados do MCP começa a exibir o tráfego da ferramenta do MCP em https://mcp.apigee.internal/mcp quando uma extração é concluída com uma configuração válida.

Antes da primeira extração bem-sucedida com uma configuração válida (porque nenhum proxy de descoberta do MCP foi implantado para sua organização ou porque o arquivo secundário não consegue acessar o plano de controle), os pods do MCP permanecem Ready, mas as solicitações para https://mcp.apigee.internal/mcp falham com conexão recusada.

Inspecione os registros do arquivo secundário para determinar em qual caso você se encontra:

kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
  • Repetição da linha info indicando que não há configuração do MCP no plano de controle:
    {"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"}
    O plano de controle da Apigee retornou uma resposta bem-sucedida, mas nenhum proxy de descoberta do MCP foi implantado para sua organização ainda. Esse é o estado estável esperado durante a integração. Para fazer a transição do plano de dados do MCP para o estado de exibição, implante um proxy de descoberta do MCP de acordo com o guia de início rápido do MCP.
  • Linha error com um 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>"}
    Os registros do arquivo secundário são JSON estruturados. Quando você vê "level":"error" com um contador consecutive_failures crescente, o arquivo secundário não conseguiu concluir uma extração de configuração. O arquivo secundário tenta novamente de forma automática com backoff e redefine o contador para 0 na próxima extração bem-sucedida.

    Causas raiz comuns a serem verificadas quando esse contador continua aumentando:

    • A conta de serviço do Google Cloud apigee-watcher não está na lista watcher_identities no recurso controlPlaneAccess da sua organização da Apigee. Consulte a Etapa 2: conceder à identidade do observador acesso à configuração do MCP no plano de controle no procedimento de ativação para adicionar a concessão e verificar se ela foi aplicada.
    • A saída do cluster para apigee.googleapis.com ou storage.googleapis.com está bloqueada. Os dois endpoints precisam ser acessíveis pelos pods do MCP. Consulte Requisitos de rede de saída no procedimento de ativação.
    • A conta de serviço apigee-watcher não pode receber tokens de acesso do Google Cloud desse cluster. Se os componentes da Apigee híbrida no mesmo namespace também estiverem relatando falhas de autenticação, resolva primeiro o problema de autenticação compartilhada.
    • Um erro temporário do plano de controle da Apigee ou do Cloud Storage. Se o contador continuar subindo por um período prolongado depois de descartar as causas acima, entre em contato com o Suporte da Apigee.

Etapa 4: verificar se os hostAliases do processador de mensagens foram injetados

Quando você ativa o MCP, o operador da Apigee injeta uma entrada hostAliases na especificação do pod do processador de mensagens (MP). A entrada contém um IP (o ClusterIP do serviço MCP) e dois nomes de host: mcp.apigee.internal e ORG_NAME.mcp.apigee.internal em letras minúsculas. Verifique se a injeção foi bem-sucedida:

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 listado precisa ter uma entrada hostAliases contendo mcp.apigee.internal e ORG_NAME.mcp.apigee.internal em letras minúsculas apontando para o ClusterIP do serviço de MCP. Qualquer pod do MP que mostre uma entrada vazia ou ausente foi criado antes da ativação do MCP. Exclua o pod de MP afetado para que o controlador ApigeeDeployment o recrie com base na especificação atual do pod, que inclui a entrada hostAliases injetada:

kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime

Etapa 5: verificação de ponta a ponta

Para um teste completo que envia uma solicitação MCP initialize real pelo plano de dados do MCP, implante um proxy de descoberta do MCP e siga o guia de início rápido do MCP. Antes que um proxy de descoberta do MCP seja implantado para sua organização, as solicitações para https://mcp.apigee.internal/mcp falham com conexão recusada, independentemente de o processador de mensagens poder alcançar os pods do MCP (consulte a etapa 3).

Etapa 6: verificar o mTLS no gateway de entrada (se configurado)

Esta etapa só se aplica se você tiver configurado virtualhosts[].mcpMtls para um grupo de ambiente (Apigee híbrida 1.17.4 e posterior). O sintoma típico de um problema de mTLS é que as chamadas da ferramenta MCP para um grupo de ambiente falham (geralmente 503 Service Unavailable), enquanto as chamadas para outros grupos de ambiente são bem-sucedidas, porque o plano de dados do MCP mantém a configuração do certificado por grupo de ambiente.

  1. Confirme se o operador aceitou o campo. O recurso de roteamento do grupo de ambientes precisa conter o bloco mcpMtls:
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    Uma segunda coluna vazia, vários minutos após o upgrade da apigee-virtualhost, geralmente significa que as definições de recursos personalizados da Apigee no cluster são mais antigas que 1.17.4 e não declaram mcpMtls. Por isso, o servidor da API descartou o campo. (Com menos frequência, o gráfico apigee-org que fornece a imagem do observador não foi atualizado para 1.17.4.) Isso acontece quando um upgrade executou helm upgrade para o gráfico do operador, mas pulou a etapa Instalar os CRDs atualizados da Apigee. O plano de dados do MCP ainda usa o TLS unidirecional, e o gateway de entrada no modo MUTUAL o rejeita. Os mesmos CRDs desatualizados também impedem que os problemas de AIS_MCP_MTLS_* na próxima etapa sejam relatados. Verifique e corrija com:
    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
    Execute o kubectl apply no diretório de gráficos do Helm e, em seguida, execute novamente o upgrade do apigee-virtualhost para o grupo de ambiente.
  2. Verifique se há problemas de certificado relatados pelo cluster. O inspetor verifica os Secrets configurados e cria um 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
    O campo Spec.Details nomeia o Secret e o ApigeeRouteConfig (chamado ORG_NAME-ENV_GROUP_NAME) a que o problema pertence, além do defeito específico.
    Motivo Gravidade Significado Corrigir
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR O Secret do certificado do cliente não existe (secret not found), não tem uma entrada cert ou key, uma entrada está vazia ou não é PEM, o certificado e a chave não correspondem ou o uso de chave estendido do certificado omite clientAuth. O plano de dados do MCP não o carrega. Crie ou corrija o Secret (opção 2) ou os arquivos seguidos por helm upgrade (opção 1). Se o problema for o uso estendido de chaves, emita novamente o certificado com clientAuth.
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY WARNING em até 14 dias após o vencimento; ERROR depois disso O certificado do cliente está prestes a expirar ou já expirou. Um certificado expirado ainda é apresentado. O gateway de entrada rejeita o handshake. Faça a rotação do certificado conforme descrito em Fazer a rotação de certificados.
    AIS_MCP_MTLS_CA_CERT_INVALID ERROR O Secret -cacert não existe (secret not found; com sslSecret, você o cria), não tem a entrada cacert, a entrada não é PEM, um bloco não é um certificado ou um certificado nele não é um certificado de CA. Crie o Secret, se necessário, e coloque o certificado de CA (ou cadeia) que assinou o certificado do gateway de entrada na entrada cacert.
    AIS_MCP_MTLS_CA_CERT_EXPIRY WARNING em até 14 dias após o vencimento; ERROR depois disso Um certificado de CA no Secret -cacert está prestes a expirar ou já expirou. Após a expiração, o plano de dados do MCP não confia mais na cadeia de certificados do gateway de entrada. Substitua o certificado de CA no Secret -cacert antes que ele expire, junto com o certificado do gateway de entrada, se ele também estiver sendo reemitido.
    Os problemas são retirados automaticamente na próxima verificação após a correção do Secret.
  3. Leia as mensagens mTLS do arquivo secundário. O contêiner apigee-mcp-server-config registra uma linha error sempre que não consegue aplicar os certificados de um grupo de ambiente. Cada linha normalmente inclui campos como env_group, secret (e um campo de secret de confiança quando a validação de cadeia está ativada), um código reason e o texto de erro encapsulado. Filtre pelo valor do código reason, que é o identificador estável. Não use os outros nomes de campo:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    Pesquise todo o registro em vez de uma janela recente: um Secret com falha é relatado quando o arquivo secundário o vê pela primeira vez (e novamente quando ele muda), não em cada atualização.

    Os códigos de motivo a seguir são estáveis para a versão atual. Se você encontrar um código que não está listado, entre em contato com o Google Cloud Customer Care.

    reason Significado Ação
    MCP_MTLS_SECRET_NOT_FOUND Um Secret referenciado não existe no namespace da Apigee. O texto error o nomeia e indica se é o Secret do cliente ou da relação de confiança. Crie o Secret com o nome exato (lembre-se do sufixo -cacert para a CA de confiança). O arquivo secundário percebe o novo Secret por conta própria.
    MCP_MTLS_MATERIAL_UNUSABLE O Secret existe, mas o conteúdo dele é rejeitado: uma chave de dados ausente ou vazia, conteúdo que não é PEM, um certificado e uma chave que não estão pareados, um certificado de cliente sem clientAuth ou um Secret de confiança sem certificado de CA. O mesmo defeito é relatado como um ApigeeIssue (etapa anterior). Corrija o conteúdo do Secret. A edição do Secret aciona uma nova tentativa.
    MCP_MTLS_SECRET_READ_FAILED, MCP_MTLS_SECRET_WATCH_FAILED, MCP_MTLS_SECRET_ACCESS_FAILED O arquivo secundário não conseguiu ler ou monitorar Secrets pela API Kubernetes (servidor de API indisponível ou o papel do MCP perdeu a permissão secrets). Uma linha MCP_MTLS_SECRET_READ_FAILED inclui o contexto de nova tentativa, e o arquivo secundário tenta novamente com espera. As outras duas informam o estado da observação de Secret do arquivo secundário, e MCP_MTLS_SECRET_READER_RECOVERED é registrado quando o acesso é retornado. Verifique se o papel do MCP ainda concede get, list, watch em secrets (consulte Limite de confiança) e se outros componentes no namespace podem acessar o servidor da API. O nome do papel termina com um sufixo gerado. Portanto, encontre-o com kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.
    MCP_MTLS_PUBLISH_FAILED Os certificados eram válidos, mas não puderam ser gravados no volume na memória do pod do MCP. O arquivo secundário tenta novamente com espera e registra MCP_MTLS_PUBLISH_RECOVERED quando a gravação é bem-sucedida. Isso não é esperado em uma operação normal. Se o problema se repetir, colete os registros do arquivo secundário e entre em contato com o Google Cloud Customer Care.
    MCP_MTLS_UNKEYABLE_ENV_GROUP O grupo de ambiente tem mcpMtls configurado, mas o valor do rótulo envGroupId não é um elemento de caminho válido. Portanto, o plano de dados do MCP disponibiliza o grupo por TLS unidirecional, e um gateway de entrada no modo MUTUAL rejeita as chamadas de ferramenta. As regras de rótulo do Kubernetes normalmente impedem esses valores, então um grupo nesse estado veio de um recurso de roteamento aplicado diretamente ao cluster. Nenhum ApigeeIssue informa isso. Confirme se o recurso de roteamento tem um rótulo válido: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Execute novamente o upgrade de apigee-virtualhost para o grupo de ambientes para que o recurso seja recriado com base no gráfico.
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION O grupo de ambiente define disableChainValidation: true e disableSanValidation: false juntos. A correspondência de SAN acontece dentro da validação que os conjuntos de validação de cadeia configuram. Portanto, com a validação de cadeia desativada, não há nada para corresponder, e a configuração é ignorada. O gráfico rejeita esse pareamento, então um grupo nesse estado veio de um recurso personalizado aplicado diretamente ao cluster. Remova disableSanValidation do bloco mcpMtls do grupo de ambientes ou defina disableChainValidation de volta como false e forneça uma CA de confiança (consulte disableSanValidation).
    MCP_MTLS_CONFLICTING_CONFIG Dois recursos de roteamento no mesmo grupo de ambiente carregam blocos mcpMtls diferentes. Portanto, o que o plano de dados do MCP usa depende da ordem em que as rotas são processadas. O grupo pode acabar apresentando um certificado do cliente diferente daquele que você configurou, e nada downstream registra qual bloco venceu. Execute novamente o upgrade de apigee-virtualhost para o grupo de ambiente e confirme se os blocos correspondem ao comando get apigeeroutes na etapa 1. Cada rota em um grupo deriva da entrada virtualhosts[] única desse grupo. Portanto, uma discordância significa que os recursos foram aplicados diretamente ao cluster ou que um upgrade anterior foi propagado apenas parcialmente.
    Exceto para MCP_MTLS_UNKEYABLE_ENV_GROUP, que descarta o grupo de ambientes para TLS unidirecional, o grupo de ambientes continua usando os últimos certificados que o arquivo secundário carregou com sucesso. Se ele nunca tiver carregado nenhum (primeira ativação), as chamadas de ferramenta do MCP para esse grupo de ambientes vão falhar até que o problema seja corrigido. Outros grupos de ambientes não são afetados. Não é necessário reiniciar o pod após a correção.

    Os MCP_MTLS_ códigos restantes não precisam de nenhuma ação. MCP_MTLS_CHAIN_VALIDATION_DISABLED e MCP_MTLS_SAN_VALIDATION_DISABLED registram que um grupo de ambientes desativou uma validação, para que a escolha permaneça detectável em uma frota. MCP_MTLS_MATERIAL_REMOVED é a limpeza de rotina depois que um grupo desativa o recurso, e MCP_MTLS_COLLECTION_FAILED significa que a limpeza não foi concluída e os arquivos de certificado do grupo ainda estão no pod. A próxima atualização tenta fazer a limpeza novamente.

  4. Se o cluster não relatar problemas e os registros do arquivo secundário estiverem limpos, mas as chamadas de ferramenta para o grupo de ambientes ainda falharem, o handshake está sendo rejeitado por um lado:
    • O gateway de entrada rejeita o certificado do cliente quando o emissor não está na CA em que o gateway de entrada confia para esse grupo de ambiente (virtualhosts[].caCertPath ou INGRESS_SECRET_NAME-cacert). Verifique com openssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE.
    • O plano de dados do MCP rejeita o certificado do gateway de entrada quando ele não se encadeia à CA em mcpMtls.caCertPath ou MCP_CLIENT_SECRET_NAME-cacert ou quando os nomes alternativos do titular não incluem o alias do host do grupo de ambiente. Verifique com openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE e inspecione os SANs com openssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName. É preferível reemitir o certificado do gateway de entrada para que ele cubra o alias do host. Somente se isso não for possível, defina mcpMtls.disableSanValidation: true para esse grupo de ambiente, o que impede que o plano de dados do MCP verifique o nome no certificado do gateway de entrada.

Histórico de consultas

Se você abrir um caso de suporte que envolva o plano de dados do MCP da Apigee híbrida, anexe a seguinte saída para acelerar o 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 e kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.
  • Saída recente de overrides.yaml e helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE (em que APIGEE_ORG_RELEASE_NAME é o nome da versão do Helm para o gráfico apigee-org; encontre-o com helm list -n APIGEE_NAMESPACE | grep apigee-org). Antes de compartilhar overrides.yaml, oculte o material secreto, incluindo:
    • Todas as chaves de conta de serviço inline em gcp.workloadIdentity, envs[].serviceAccountPaths ou mcpServer.serviceAccountPath.
    • Todos os certificados TLS ou chaves privadas em virtualhosts.
    • Os campos de senha cassandra.auth.
    • Todas as credenciais inline que as substituições transmitem ao operador.
  • O comando curl completo e a resposta que reproduz o problema.

Não é possível mudar o estilo da API para MCP no hub de APIs

Se um recurso de API com operações de API já estiver presente no hub de APIs da Apigee, não será possível alterar o atributo Estilo da API desse recurso para MCP. Para registrar uma API no hub de APIs da Apigee como uma API MCP, selecione o estilo MCP ao registrar a API pela primeira vez ou verifique se não há operações no recurso da API antes de mudar o estilo para MCP.

Se você encontrar outros problemas, consulte Como usar a depuração para mais informações sobre como usar a ferramenta de depuração no console do Google Cloud para analisar solicitações e respostas de e para o proxy de descoberta do MCP.