Solucionar problemas do MCP server

Esta página lista os sintomas que você pode encontrar com os MCP servers da Azion, cada um com a causa e a correção. A autenticação e a conexão vêm primeiro. Em seguida vêm as ferramentas ausentes, a configuração do cliente, as respostas das ferramentas e o login. Quando um sintoma persistir, entre em contato com o suporte da Azion como Diretrizes de suporte descreve, com a mensagem de erro, a URL do servidor, o cliente e a versão dele, a configuração sem o token e os passos que reproduzem o sintoma.

O servidor responde 401 com No authentication provided

O cliente não consegue se conectar, e o servidor responde 401 com este corpo:

A requisição chegou ao servidor sem um header Authorization. A configuração do cliente não tem o header, ou o cliente não o envia.

• Adicione o header à configuração do cliente: envie Authorization: Token [TOKEN VALUE] com o seu personal token. Para a configuração de cada cliente, consulte Configuração de agentes.

O servidor responde 200 ao cliente, e o cliente lista as ferramentas.

O servidor responde 403 Authentication failed ou 401 OAuth validation failed

O cliente envia um header Authorization, e o servidor ainda recusa a requisição. O status e a mensagem indicam o problema:

Os dois chegam como objetos de erro JSON-RPC com o código -32001.

• Envie o personal token com Token: Authorization: Token [TOKEN VALUE]. Um personal token enviado com Bearer falha.
• Verifique o token: um personal token tem 40 caracteres e começa com azion. Copie o valor inteiro. Verifique se o token está ativo, se não expirou e se tem as permissões de que você precisa. Para criar outro, consulte Como criar um personal token.
• Teste a conexão com o MCP Inspector: execute npx @modelcontextprotocol/inspector, escolha o transporte streamable-http, insira a URL do servidor e passe o header com o seu token.

O servidor responde 200, e o cliente lista as ferramentas.

O cliente excede o tempo limite ou não alcança o servidor

Uma requisição excede o tempo limite, o servidor não envia resposta, ou o cliente informa um erro de rede.

O cliente aponta para a URL errada, ou a rede entre o cliente e o servidor bloqueia a conexão.

• Verifique a URL: cada servidor responde no caminho /mcp do host dele, como https://docs-mcp.azion.com/mcp. Para todas as URLs, consulte Ferramentas e recursos.
• Teste se o servidor está acessível: uma requisição sem token responde 401. Um 401 significa que o servidor está acessível. Um tempo limite excedido ou um erro de conexão significa que a rede não o alcança.
• Tente outra rede: uma VPN pode interferir. Um firewall ou um proxy precisa permitir tráfego HTTPS para o host de cada servidor que você usa, como docs-mcp.azion.com.
• Teste o seu token fora do cliente: envie a requisição initialize com curl.

Esta requisição abre uma conexão com o servidor de docs usando o seu token:

Uma resposta que traz um result com a versão do protocolo e as capacidades do servidor significa que o servidor e o token funcionam, e a correção está na configuração do cliente. Um 401 ou 403 aponta para o header, como descrevem as seções acima.

Uma ferramenta está ausente ou uma chamada falha com Tool not found

O agente não oferece uma ferramenta que você espera, ou uma chamada de ferramenta falha porque o servidor não conhece a ferramenta.

Cada servidor expõe as ferramentas da própria área, e o agente vê apenas as ferramentas dos servidores que ele conecta. Uma ferramenta de uma área cujo servidor não está conectado fica ausente, e uma chamada que indica uma ferramenta no servidor errado falha.

• Conecte o servidor responsável pela ferramenta: o servidor de docs busca e retorna guias, o de build gerencia aplicações, regras, functions, workloads e purge de cache, o de secure gerencia firewalls, WAF, DNS e certificados, o de observe gerencia data streams, relatórios e queries GraphQL, e o de storage gerencia o Object Storage e o SQL Database. Para as ferramentas de cada servidor, consulte Ferramentas e recursos.
• Verifique os servidores conectados: no Claude Code, claude mcp list indica cada servidor e o status dele.
• Chame as ferramentas que o servidor lista: o agente chama apenas as ferramentas que tools/list retorna para cada servidor.

O agente lista a ferramenta, e a chamada responde.

A conexão falha com TLSV1_ALERT_PROTOCOL_VERSION

O cliente falha no handshake TLS com um erro como SSLError TLSV1_ALERT_PROTOCOL_VERSION.

Os servidores aceitam somente TLS 1.3. Um cliente construído sobre uma biblioteca TLS sem TLS 1.3, como LibreSSL 2.8.3, não consegue se conectar.

• Execute o cliente em um runtime com TLS 1.3: um runtime cuja biblioteca TLS suporta TLS 1.3 se conecta, como o Node.js 24.
• Verifique a biblioteca TLS da sua ferramenta: um script ou um proxy entre o cliente e o servidor também precisa suportar TLS 1.3.

O handshake é concluído, e o servidor responde à requisição.

O cliente não mostra ferramentas da Azion

O cliente não mostra ferramentas da Azion, informa No tools available ou não reconhece os comandos.

O cliente não suporta MCP, não carregou a configuração dele ou não registrou o servidor.

• Verifique o suporte a MCP: use uma versão do cliente que suporte MCP. Atualize o cliente se ele não suportar.
• Verifique o local da configuração: o Windsurf lê .codeium/windsurf/mcp_config.json. Para cada cliente, consulte Configuração de agentes.
• Verifique se o servidor está registrado: no Claude Code, claude mcp list nomeia os servidores que ele conhece. Para a configuração, consulte Claude Code + Azion.
• Reinicie o cliente: feche e abra a aplicação novamente para que ela leia a configuração outra vez.

O cliente lista as ferramentas de cada servidor que ele conecta.

O cliente informa Invalid JSON

O cliente informa Invalid JSON e não carrega a configuração.

O arquivo de configuração quebra uma regra do JSON. As causas comuns são uma vírgula faltando entre propriedades, uma vírgula final, aspas simples em vez de aspas duplas e um colchete ou uma chave sem fechamento.

• Valide o arquivo: cat mcp_config.json | python -m json.tool imprime o arquivo quando ele é válido e indica o primeiro erro quando não é.
• Compare com uma configuração válida: um cliente que inicia o servidor pelo mcp-remote lê uma configuração neste formato.

O cliente carrega a configuração e lista as ferramentas.

O cliente falha com npx command not found

O cliente falha com npx: command not found ou Node.js is required.

O mcp-remote é executado no Node.js. Ele precisa do Node.js 18 ou posterior, e o npx vem com o npm.

• Verifique as versões instaladas: node --version e npm --version imprimem as versões, ou falham quando o Node.js não está instalado.
• Instale o Node.js: no macOS, execute brew install node. No Ubuntu ou no Debian, execute sudo apt install nodejs npm.
• Atualize o npm: execute npm install -g npm@latest.

npx -y mcp-remote@latest inicia a ponte. Para os clientes que a usam, consulte Configuração de agentes.

O cliente falha com Cannot find module mcp-remote

O cliente falha com Cannot find module 'mcp-remote', ou a instalação do pacote falha.

O cache do npm ou a cópia instalada do mcp-remote está corrompida ou ausente.

• Limpe o cache do npm: execute npm cache clean --force.
• Instale o pacote globalmente: execute npm install -g mcp-remote.
• Execute a versão mais recente: inicie a ponte com npx mcp-remote@latest.

A ponte inicia e imprime Proxy established successfully.

Uma busca retorna documentos que não correspondem à query

Uma ferramenta de busca não retorna nenhum resultado, retorna um resultado parcial ou retorna respostas genéricas em vez de informações da Azion.

As ferramentas de busca classificam os documentos pela proximidade com as palavras da query, não pelo que a query significa. Uma query ampla pode colocar em primeiro lugar um documento sobre outro produto ou outra operação.

• Nomeie o produto e a tarefa: pergunte “Como configuro o TTL de cache para imagens na Azion?” em vez de “Ajuda com cache”.
• Nomeie a ferramenta ou a fonte: peça “Busque na documentação da Azion a configuração de cache do Rules Engine”.
• Peça mais documentos: as ferramentas de busca recebem docsAmount, cujo padrão é 5. Para as entradas, consulte Ferramentas.
• Divida a requisição: faça uma pergunta por prompt.

A ferramenta retorna documentos sobre o produto e a tarefa que você nomeou.

A ferramenta GraphQL responde It was not possible to retrieve the requested information

create_graphql_query, no servidor de observe, retorna o texto It was not possible to retrieve the requested information with GraphQL. em vez de uma query. Em seguida, o texto aponta para a documentação da GraphQL API.

A ferramenta escreve uma query para o seu objetivo e a executa no endpoint GraphQL selecionado da sua conta, com o seu token. A ferramenta retorna esse texto quando não consegue produzir uma query que seja executada. O servidor não retorna a causa ao cliente.

• Verifique se os dados existem: confirme que a GraphQL API traz os dados que você pede. Para os datasets, consulte GraphQL API.
• Verifique a fonte de dados: dataSource recebe real-time-metrics, real-time-events, accounting ou consumption. Escolha a que contém os dados.
• Escreva a query você mesmo: monte a query a partir da documentação da GraphQL API e execute-a na GraphQL API.

Você obtém os dados de uma query que a GraphQL API executa.

As chamadas de ferramentas respondem devagar

As chamadas de ferramentas demoram para responder.

O caminho de rede até o servidor é lento, muitas requisições são executadas ao mesmo tempo, ou a query é ampla. create_graphql_query, no servidor de observe, também gera e executa queries na sua conta, então demora mais que uma busca.

• Verifique a rede: use uma conexão estável. ping docs-mcp.azion.com mede a latência até o servidor de docs.
• Envie menos requisições ao mesmo tempo: execute menos chamadas de ferramentas simultâneas.
• Restrinja a query: faça uma pergunta específica em vez de uma busca ampla.

As chamadas de ferramentas respondem em menos tempo.

Recursos relacionados