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 de 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 da 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 é 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 nenhum metadado de recurso sem proteção está disponível 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 processam esses códigos de status com 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 do MCP Discovery.

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 o 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 padrão. 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 espera e redefine o contador para 0 na próxima extração bem-sucedida.

    Causas raiz comuns para verificar 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 híbridos da Apigee 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 do 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 acessar 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 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 do 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 mudar 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 de API antes de mudar o estilo para MCP.

Se você encontrar outros problemas, consulte Como usar a depuração para informações detalhadas 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.