# Solucionar problemas do MCP server Esta página lista os sintomas que você pode encontrar com os [MCP servers da Azion](/pt-br/documentacao/devtools/mcp/), 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](/pt-br/documentacao/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: ```json {"jsonrpc":"2.0","error":{"code":-32001,"message":"No authentication provided"},"id":null} ``` 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](/pt-br/documentacao/agent-setup/). 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: | Status | Mensagem | Causa | | ------ | ------------------------- | --------------------------------------------------------- | | `403` | `Authentication failed` | O valor depois de `Token` não é um personal token válido. | | `401` | `OAuth validation failed` | O personal token foi enviado com o esquema `Bearer`. | 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](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). - **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. > **Atenção** > > Mantenha o seu personal token fora do controle de versão e fora de mensagens para outras pessoas. Remova-o de logs, capturas de tela e prévias `dry_run` antes de enviá-los. 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](/pt-br/documentacao/devtools/mcp/ferramentas/). - **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: ```bash curl -s https://docs-mcp.azion.com/mcp \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0.1"}}}' ``` 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](/pt-br/documentacao/devtools/mcp/ferramentas/). - **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](/pt-br/documentacao/agent-setup/). - **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](/pt-br/documentacao/agent-setup/claude-code/). - **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. ```json { "mcpServers": { "azion-docs": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://docs-mcp.azion.com/mcp", "--header", "Authorization: Token [TOKEN VALUE]" ] } } } ``` 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](/pt-br/documentacao/agent-setup/). --- ## 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](/pt-br/documentacao/devtools/mcp/ferramentas/#ferramentas-do-servidor-de-docs). - **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](/pt-br/documentacao/devtools/graphql/). - **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 - [Primeiros passos com o MCP server](/pt-br/documentacao/devtools/mcp/primeiros-passos.md): Crie um personal token e conecte um cliente, a configuração à qual a maioria das correções desta página retorna. - [Ferramentas e recursos](/pt-br/documentacao/devtools/mcp/ferramentas.md): A URL e as ferramentas de cada servidor, as entradas delas e os recursos que o servidor de docs expõe. - [Como o MCP server funciona](/pt-br/documentacao/devtools/mcp/como-funciona.md): Como os servidores autenticam uma requisição, respondem a ela e mostram uma prévia de escrita com dry\_run. - [Configuração de agentes](/pt-br/documentacao/agent-setup.md): A configuração de cada agente de código, incluindo o esquema de header que ele envia.