Resolução de Problemas

Esta página aborda problemas comuns em ambas as Docker e npm. Problemas que se aplicam a apenas 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 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 definidos)
• 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 verificação do servidor de desenvolvimento local com ERR_CONNECTION_REFUSED

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

Se a ferramenta analyze falhar com um erro net::ERR_CONNECTION_REFUSED ao tentar verificar um servidor de desenvolvimento em execução localmente, isso provavelmente ocorre porque o axe MCP Server é executado dentro de um contêiner Docker e não pode acessar serviços vinculados apenas ao localhost (ou seja, 127.0.0.1) no seu host.

Exemplo de erro:

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

Solução: Inicie seu servidor de desenvolvimento com a flag --host definida para 0.0.0.0 para que ele escute em todas as interfaces de rede, tornando-o acessível a partir 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 ao distribuição npm. A distribuição Docker inclui seu próprio navegador, portanto, 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 axe MCP Server executa varreduras de acessibilidade dirigindo um navegador real através de Playwright. Com a distribuição npm, esse navegador — o 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 que o servidor envia espera, o servidor falha ao iniciar (ou falha na primeira verificação) com um erro indicando que o Chromium não pôde ser lançado.

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 que o axe MCP Server envia — atualmente 1.60.0. Fixe o Playwright para essa versão para que um comando básico npx playwright não resolva uma versão mais recente 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 já tiver um binário compatível do Chrome/Chromium no seu host, você pode evitar a instalação do Playwright completamente definindo a variável de ambiente AXE_CHROME_PATH para esse binário. Este é frequentemente o ajuste mais rápido 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 — note que o Google Chrome estável 137+ não é suportado, e o valor deve ser um binário executável em vez de um pacote .app.

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. Incorporar um binário de navegador no pacote npm inflaria significativamente seu tamanho, amarraria o pacote a um binário de uma plataforma e ficaria obsoleto assim que o Playwright atualizasse sua revisão fixada. Instalar o Chromium através do Playwright, em vez disso, garante que você obtenha exatamente a revisão que sua versão instalada espera, para sua plataforma. (A distribuição Docker pode embutir um navegador porque a imagem é construída para um ambiente único e 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 diferente da atualmente instalada. Quando isso acontece, você pode ver o mesmo erro de lançamento novamente após uma atualização. A solução é a mesma — executar novamente a instalação com a versão do Playwright que o servidor atualizado envia para que o Chromium corresponda:

npx playwright@1.60.0 install chromium

Como regra geral, execute novamente este comando — usando a versão do Playwright que a versão atual envia — sempre que você atualizar axe-mcp-server e o servidor relatar uma incompatibilidade de 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 a URL do seu servidor axe está correta — se sua organização usa uma instância regional, nuvem privada ou on-premises do axe, AXE_SERVER_URL deve ser definido para a 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 se você tem um token válido; se ele sair com um código diferente de zero, reautentique com npx @deque/axe-auth login
• Confirme que o URL do servidor axe está correto
• Se seu token expirou no meio da sessão, reinicie a conexão do servidor MCP no seu cliente (por exemplo, reiniciando o Claude Code, alternando o servidor desligado e ligado nas configurações MCP do Cursor, ou clicando no botão "Reiniciar" do CodeLens do VS Code diretamente acima da entrada do axe MCP Server 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/desenvolvedor do seu cliente MCP para mensagens de erro detalhadas (por exemplo, o Console de Desenvolvedor do VS Code, as Ferramentas de Desenvolvedor do Cursor, ou a saída --debug do Claude Code)
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. Entre em contato com nossa equipe de suporte em helpdesk@deque.com com:
   • Seu cliente MCP e sua versão
   • 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