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 resolver 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 de erro e verificar a conectividade de tempo de execução.

Entender 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 na infraestrutura da Apigee e do Google Cloud antes da conclusão da implantação do proxy.

Enquanto essas etapas de provisionamento downstream estão sendo realizadas, a UI mostra o proxy no status Provisionando. Quando o processo for concluído, o status 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 ocorrer ao usar o MCP na Apigee.

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 processar corretamente os erros no seu cliente da 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 da MCP e o agente de LLM leiam o erro e se recuperem (por exemplo, ao solicitar novamente a entrada ausente e tentar de novo) em vez de encerrar a sessão.
Os metadados do recurso protegido por OAuth (PRM) 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 protegidos 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 aumento de privilégios.

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

Quando uma chamada de ferramenta falha, o Apigee MCP retorna HTTP 200 OK e informa a falha no objeto JSON-RPC result, com isError definido como true. O erro original retornado pelo seu 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)..

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

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 error JSON-RPC (por exemplo, {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) em vez de result.isError.

Recomendação:os clientes MCP compatíveis com padrões processam esses códigos de status com a lógica padrão. Portanto, nenhuma mudança é necessária. Se você adicionou uma solução alternativa do lado do cliente para processar 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 da 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 ativar chamadas baseadas em navegador.

Se você encontrar 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 JSON ao enviar solicitação para o endpoint do MCP

Você pode receber uma mensagem de erro semelhante a esta (ou com um código 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 que você confirme as seguintes informações:

  • Você inseriu o URL do endpoint do MCP correto.
  • 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 compatível. Para uma lista de regiões que podem ter limites de capacidade, consulte falhas de implantação.

Falhas de implantação

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

  • Falha na configuração de rede ou Esquema não compatível em 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ê encontrar um erro relacionado à falha no 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 da 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 de outra região. Esse modo de falha não se aplica à Apigee híbrida, em que a infraestrutura de ambiente de execução é seu próprio cluster.

  • MCP não ativado no cluster (somente Apigee híbrida): se a implantação do proxy do MCP permanecer no status Provisionando indefinidamente e nunca atingir 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 da MCP híbrida do Apigee é 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 na ordem.

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 ApigeeDeployment do MCP:

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

Saída esperada (os nomes de 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 estará 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 seu 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 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 lançamento híbrido de quatro dígitos (por exemplo, 1170 para o híbrido 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 no pull de imagens (verifique a saída do cluster para o registro de imagens configurado em overrides.yaml) e headroom insuficiente de CPU ou memória (aumente mcpServer.resources.requests em overrides.yaml).

Etapa 3: verificar o status do pull da configuração do sidecar

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 busca o pacote de configuração referenciado do Cloud Storage. O plano de dados do MCP começa a veicular o tráfego da ferramenta do MCP em https://mcp.apigee.internal/mcp assim que um pull é concluído com uma configuração válida.

Antes da primeira extração bem-sucedida com uma configuração válida (porque ainda não foi implantado um proxy de descoberta do MCP para sua organização ou porque o sidecar não consegue alcançar 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 sidecar para determinar em qual caso você está:

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 serviç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 sidecar são JSON estruturados. Quando você vê "level":"error" com um contador consecutive_failures crescente, o sidecar não concluiu um pull de configuração. O sidecar tenta novamente de forma automática com backoff e redefine o contador para 0 no próximo pull bem-sucedido.

    Causas 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 do recurso controlPlaneAccess da organização da Apigee. Consulte 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 concluída.
    • A saída do cluster para apigee.googleapis.com ou storage.googleapis.com está bloqueada. Os dois endpoints precisam estar acessíveis dos 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 informando 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 aumentando 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 do 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 o 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 do MP listado precisa ter uma entrada hostAliases que contenha mcp.apigee.internal e ORG_NAME.mcp.apigee.internal em letras minúsculas apontando para o ClusterIP do serviço MCP. Qualquer pod do MP que mostre uma entrada vazia ou ausente foi criado antes da ativação do MCP. Exclua o pod do MP afetado para que o controlador ApigeeDeployment o recrie com base na especificação do pod atual (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 de ponta a ponta que envia uma solicitação initialize real do MCP pelo plano de dados do MCP, implante um proxy de descoberta do MCP e siga o 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 independente de o processador de mensagens conseguir alcançar os pods do MCP (consulte a etapa 3).

Histórico de consultas

Se você abrir um caso de suporte que envolva o plano de dados da MCP híbrida da Apigee, 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 do gráfico apigee-org. Para encontrar, use helm list -n APIGEE_NAMESPACE | grep apigee-org). Antes de compartilhar overrides.yaml, oculte 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 suas substituições transmitem ao operador.
  • O comando e a resposta curl completos que reproduzem 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 mudar o atributo Estilo da API desse recurso para MCP. Para registrar uma API com o hub de APIs da Apigee como uma API do MCP, selecione o estilo MCP ao registrar a API pela primeira vez ou verifique se não há operações presentes no recurso de API antes de mudar o estilo para MCP.

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