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.
O back-end não recebe um argumento de ferramenta no local esperado
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.
O back-end para de receber um cookie que a solicitação do cliente do MCP carregava
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-east2asia-northeast3asia-southeast2australia-southeast1europe-central2europe-west12europe-west9me-central2us-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
infoindicando que não há configuração do MCP no plano de controle: 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.{"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"} - Linha
errorcom um contadorconsecutive_failures: Os registros do arquivo secundário são JSON estruturados. Quando você vê{"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}"level":"error"com um contadorconsecutive_failurescrescente, 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-watchernão está na listawatcher_identitiesno recursocontrolPlaneAccessda 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.comoustorage.googleapis.comestá 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-watchernã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.
- A conta de serviço do Google Cloud
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.
- Confirme se o operador aceitou o campo. O recurso de roteamento do grupo de ambientes precisa conter o bloco
mcpMtls: Uma segunda coluna vazia, vários minutos após o upgrade dakubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
apigee-virtualhost, geralmente significa que as definições de recursos personalizados da Apigee no cluster são mais antigas que1.17.4e não declarammcpMtls. Por isso, o servidor da API descartou o campo. (Com menos frequência, o gráficoapigee-orgque fornece a imagem do observador não foi atualizado para1.17.4.) Isso acontece quando um upgrade executouhelm upgradepara 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 modoMUTUALo rejeita. Os mesmos CRDs desatualizados também impedem que os problemas deAIS_MCP_MTLS_*na próxima etapa sejam relatados. Verifique e corrija com: Execute okubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls # 0 means the CRDs are stale kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
kubectl applyno diretório de gráficos do Helm e, em seguida, execute novamente o upgrade doapigee-virtualhostpara o grupo de ambiente. - Verifique se há problemas de certificado relatados pelo cluster. O inspetor verifica os
Secrets configurados e cria um
ApigeeIssuepara cada problema: O campokubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)' kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
Spec.Detailsnomeia o Secret e oApigeeRouteConfig(chamadoORG_NAME-ENV_GROUP_NAME) a que o problema pertence, além do defeito específico.
Os problemas são retirados automaticamente na próxima verificação após a correção do Secret.Motivo Gravidade Significado Corrigir AIS_MCP_MTLS_CLIENT_CERT_INVALIDERRORO Secret do certificado do cliente não existe ( secret not found), não tem uma entradacertoukey, uma entrada está vazia ou não é PEM, o certificado e a chave não correspondem ou o uso de chave estendido do certificado omiteclientAuth. 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 comclientAuth.AIS_MCP_MTLS_CLIENT_CERT_EXPIRYWARNINGem até 14 dias após o vencimento;ERRORdepois dissoO 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_INVALIDERRORO Secret -cacertnão existe (secret not found; comsslSecret, você o cria), não tem a entradacacert, 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_EXPIRYWARNINGem até 14 dias após o vencimento;ERRORdepois dissoUm certificado de CA no Secret -cacertestá 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 -cacertantes que ele expire, junto com o certificado do gateway de entrada, se ele também estiver sendo reemitido. - Leia as mensagens mTLS do arquivo secundário. O contêiner
apigee-mcp-server-configregistra uma linhaerrorsempre que não consegue aplicar os certificados de um grupo de ambiente. Cada linha normalmente inclui campos comoenv_group,secret(e um campo de secret de confiança quando a validação de cadeia está ativada), um códigoreasone o texto de erro encapsulado. Filtre pelo valor do códigoreason, que é o identificador estável. Não use os outros nomes de campo: 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.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
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.
Exceto parareasonSignificado Ação MCP_MTLS_SECRET_NOT_FOUNDUm Secret referenciado não existe no namespace da Apigee. O texto erroro 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 -cacertpara a CA de confiança). O arquivo secundário percebe o novo Secret por conta própria.MCP_MTLS_MATERIAL_UNUSABLEO 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 clientAuthou um Secret de confiança sem certificado de CA. O mesmo defeito é relatado como umApigeeIssue(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_FAILEDO 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 linhaMCP_MTLS_SECRET_READ_FAILEDinclui 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, eMCP_MTLS_SECRET_READER_RECOVEREDé registrado quando o acesso é retornado.Verifique se o papel do MCP ainda concede get,list,watchemsecrets(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 comkubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.MCP_MTLS_PUBLISH_FAILEDOs 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_RECOVEREDquando 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_GROUPO grupo de ambiente tem mcpMtlsconfigurado, mas o valor do rótuloenvGroupIdnã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 modoMUTUALrejeita 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. NenhumApigeeIssueinforma 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 deapigee-virtualhostpara o grupo de ambientes para que o recurso seja recriado com base no gráfico.MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATIONO grupo de ambiente define disableChainValidation: trueedisableSanValidation: falsejuntos. 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 disableSanValidationdo blocomcpMtlsdo grupo de ambientes ou definadisableChainValidationde volta comofalsee forneça uma CA de confiança (consultedisableSanValidation).MCP_MTLS_CONFLICTING_CONFIGDois recursos de roteamento no mesmo grupo de ambiente carregam blocos mcpMtlsdiferentes. 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-virtualhostpara o grupo de ambiente e confirme se os blocos correspondem ao comandoget apigeeroutesna etapa 1. Cada rota em um grupo deriva da entradavirtualhosts[]ú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.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_DISABLEDeMCP_MTLS_SAN_VALIDATION_DISABLEDregistram 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, eMCP_MTLS_COLLECTION_FAILEDsignifica 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. - 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[].caCertPathouINGRESS_SECRET_NAME-cacert). Verifique comopenssl 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.caCertPathouMCP_CLIENT_SECRET_NAME-cacertou quando os nomes alternativos do titular não incluem o alias do host do grupo de ambiente. Verifique comopenssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILEe inspecione os SANs comopenssl 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, definamcpMtls.disableSanValidation: truepara esse grupo de ambiente, o que impede que o plano de dados do MCP verifique o nome no certificado do gateway de entrada.
- 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
(
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=1000kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-serverkubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wideekubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.- Saída recente de
overrides.yamlehelm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE(em queAPIGEE_ORG_RELEASE_NAMEé o nome da versão do Helm para o gráficoapigee-org; encontre-o comhelm list -n APIGEE_NAMESPACE | grep apigee-org). Antes de compartilharoverrides.yaml, oculte o material secreto, incluindo:- Todas as chaves de conta de serviço inline em
gcp.workloadIdentity,envs[].serviceAccountPathsoumcpServer.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.
- Todas as chaves de conta de serviço inline em
- O comando
curlcompleto 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.