Resolução de Problemas

Esta página cobre problemas comuns tanto nas distribuições de Docker e npm. Problemas que se aplicam apenas a uma distribuição são rotulados de acordo.

Servidor não inicia

• Certifique-se de que o Docker está em execução (distribuição Docker) ou de que o Chromium está instalado (distribuição npm — veja instalação do Chromium)
• Verifique se suas credenciais estão corretas: ou seu AXE_API_KEY ou seu AXE_ACCESS_TOKEN, mas não ambos (o servidor falha na inicialização se ambos estiverem configurados)
• Verifique se você tem acesso ao servidor axe MCP (contate o suporte se necessário)

Tempo limite de varredura

• Aumente BROWSER_TIMEOUT_MS para páginas complexas
• Certifique-se de que o URL de destino é acessível a partir da sua rede
• Verifique problemas de conectividade de rede

Falha na varredura do servidor de desenvolvimento local com ERR_CONNECTION_REFUSED

Isso se aplica à distribuição Docker — com a distribuição npm, o servidor é executado diretamente em seu host e pode acessar localhost serviços normalmente.

Se a analyze ferramenta falhar com um net::ERR_CONNECTION_REFUSED erro ao tentar escanear um servidor de desenvolvimento local em execução, isso provavelmente ocorre porque o servidor axe MCP executa dentro de um contêiner Docker e não consegue acessar serviços vinculados apenas a localhost (ou seja, 127.0.0.1) em sua máquina host.

Exemplo de erro:

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Solução: Inicie seu servidor de desenvolvimento com a --host opção configurada para 0.0.0.0 para que ele escute em todas as interfaces de rede, tornando-o acessível de dentro do contêiner Docker:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Problemas com Docker

• Certifique-se de que o daemon do Docker está em execução
• Verifique as permissões do Docker
• Verifique a conectividade de rede para downloads de imagens do Docker
• Certifique-se de que o Docker tem memória suficiente executando um docker system prune

Instalação do Chromium (npm)

Esta seção se aplica à distribuição npm. A distribuição Docker vem com seu próprio navegador, então os usuários do Docker não precisam instalar o Chromium e não são afetados pelos erros descritos aqui.

O que o erro significa

O servidor axe MCP executa varreduras de acessibilidade por meio de um navegador real com Playwright. Com a distribuição npm, esse navegador — Chromium — deve estar instalado no seu host. Se estiver ausente ou se a versão instalada não corresponder à revisão do Chromium que a versão do Playwright fornecida pelo servidor espera, o servidor falha ao iniciar (ou falha na primeira varredura) com um erro indicando que o Chromium não pôde ser iniciado.

Isso é esperado em uma instalação nova e é fácil de corrigir.

Correção padrão

Instale a revisão do Chromium que corresponde à versão do Playwright fornecida pelo servidor axe MCP — atualmente 1.60.0. Fixe o Playwright nessa versão para que uma instalação comum npx playwright não resolva para uma nova versão com uma revisão do Chromium que o servidor não suporta:

npx playwright@1.60.0 install chromium

Em seguida, reinicie o servidor MCP (ou seu cliente MCP) e tente novamente.

Complemento para Linux

No Linux, o Chromium também depende de várias bibliotecas do sistema que podem não estar presentes. Se o navegador ainda falhar ao iniciar após a correção padrão, instale essas dependências:

sudo npx playwright@1.60.0 install-deps chromium

Você também pode combinar ambos os passos em um único comando:

sudo npx playwright@1.60.0 install --with-deps chromium

Use um navegador que você já possui

Se você já possui um binário compatível do Chrome/Chromium no seu host, pode contornar a instalação do Playwright completamente configurando a variável de ambiente AXE_CHROME_PATH para esse binário. Esta é frequentemente a solução mais rápida quando o download do Playwright está bloqueado (rede restrita, proxy) ou quando instalar dependências do sistema não é uma opção. Veja AXE_CHROME_PATH para os requisitos — observe que o Google Chrome estável 137+ não é suportado, e o valor deve ser um binário executável em vez de um .app pacote.

Por que o Chromium não está incluído

O Playwright fixa uma revisão específica do Chromium para cada versão do Playwright, e essa revisão muda com o tempo. Incluir um binário do navegador no pacote npm aumentaria significativamente seu tamanho, prenderia o pacote ao binário de uma plataforma e ficaria obsoleto assim que o Playwright atualizasse sua revisão fixa. Instalar o Chromium através do Playwright, em vez disso, garante que você obtenha exatamente a revisão que a versão instalada espera, para sua plataforma. (A distribuição Docker pode incluir um navegador porque a imagem é construída para um único ambiente conhecido.)

Reexecutando após uma atualização do axe-mcp-server

Atualizar axe-mcp-server pode trazer uma versão mais recente do Playwright, que pode fixar uma revisão mais recente do Chromium do que a atualmente instalada. Quando isso acontecer, você pode ver o mesmo erro de inicialização novamente após uma atualização. A correção é a mesma — execute a instalação novamente com a versão do Playwright que o servidor atualizado fornece para que o Chromium corresponda:

npx playwright@1.60.0 install chromium

Como regra geral, execute este comando novamente — usando a versão do Playwright que a versão atual oferece — sempre que atualizar axe-mcp-server e o servidor relatar uma incompatibilidade do Chromium na inicialização.

Erros de autenticação

Chave de API

• Verifique se a sua chave de API é válida e não expirou
• Certifique-se de que sua assinatura do Portal de Conta axe inclui acesso ao Servidor MCP
• Verifique se a chave de API foi criada para o produto "axe MCP Server"
• Confirme que apenas AXE_API_KEY está definido — se AXE_ACCESS_TOKEN também estiver definido, o servidor falhará na inicialização
• Confirme que o URL do servidor axe está correto — se sua organização utiliza uma instância regional, nuvem privada ou on-premises do axe, AXE_SERVER_URL deve ser definido como o URL base da sua instância. Veja Referência de Configuração para detalhes.

OAuth

• Confirme que apenas AXE_ACCESS_TOKEN está definido — se AXE_API_KEY também estiver definido, o servidor falhará na inicialização
• Execute npx @deque/axe-auth token no seu terminal para confirmar que você tem um token válido; se ele sair com um código diferente de zero, re-autentique com npx @deque/axe-auth login
• Confirme que o URL do servidor axe está correto
• Se o seu token expirar no meio da sessão, reinicie a conexão do servidor MCP no seu cliente (por exemplo, reiniciando o Claude Code, alternando o servidor ativado e desativado nas configurações do MCP do Cursor ou clicando no botão "Reiniciar" do CodeLens do VS Code diretamente acima da entrada do servidor MCP do axe em mcp.json) para obter um token novo
• Veja Autenticação para etapas completas de solução de problemas do OAuth

Obtendo Ajuda

Se você encontrar problemas não cobertos nesta seção de solução de problemas:

1. Verifique o Console do Desenvolvedor do VS Code para mensagens de erro detalhadas
2. Revise os logs do servidor — os logs do contêiner Docker, ou os logs do seu cliente MCP ao usar a distribuição npm
3. Contate nossa equipe de suporte em helpdesk@deque.com com:
   • Sua versão do VS Code
   • Sua versão do Docker (distribuição Docker) ou a versão do Node.js (distribuição npm)
   • Mensagens de erro completas
   • Passos para reproduzir o problema