Referência de Configuração

Esta página documenta as variáveis de ambiente que o Axe MCP Server lê e as instruções personalizadas recomendadas para o seu agente de IA. Elas se aplicam a ambos os distribuições Docker e npm. Para saber onde colocar esses valores, consulte seu guia de configuração do cliente.

Opções de Configuração

O Axe MCP Server suporta várias variáveis de ambiente para personalização:

AXE_SERVER_URL

O valor padrão (https://axe.deque.com) é correto para a maioria dos usuários — aqueles na instância SaaS compartilhada dos EUA da Deque. Se a sua organização usar qualquer uma das opções abaixo, você deve definir AXE_SERVER_URL para a URL base da sua instância:

• Uma instância regional de SaaS (UE, Austrália, Frankfurt, etc.)
• Um nuvem privada deployment
• Uma instalação on-premises

Se você não tiver certeza de qual instância sua organização usa, verifique a URL que você usa para fazer login no Portal de Contas Axe ou pergunte ao seu administrador.

Defina AXE_SERVER_URL explicitamente no bloco env da configuração do servidor MCP. Os guias de configuração do cliente incluem exemplos mostrando exatamente onde adicioná-lo.

AXE_CHROME_PATH

distribuição npm apenas. Isso não é suportado no Docker, que sempre usa seu navegador empacotado — o servidor falha ao iniciar se AXE_CHROME_PATH for configurado na distribuição Docker.

Por padrão, a distribuição npm usa a compilação Chromium que você instala através de Playwright. Defina AXE_CHROME_PATH para o caminho completo de um binário Chrome/Chromium existente para usar isso em vez e pular a instalação do Playwright.

• O valor deve ser um arquivo binário executável, não um pacote .app ou diretório. No macOS, por exemplo, aponte para o binário dentro do pacote: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• O binário deve existir e, no macOS e Linux, deve iniciar e responder a --version. O servidor verifica isso na inicialização e, se não conseguir, para com uma mensagem que explica o motivo, como o arquivo não ser executável ou uma biblioteca do sistema estar ausente. No Windows, o servidor apenas verifica se o arquivo existe, portanto um binário que não pode iniciar falha quando a primeira varredura começa.
• Google Chrome estável de marca 137 e superior não é suportado. Use Chrome para Testes ou outro binário compatível com Chromium.

As ferramentas analyze e igt também aceitam um argumento chromePath por chamada, que tem precedência sobre AXE_CHROME_PATH para essa chamada.

AXE_ADVANCED_RULES

Define o predefinição de confiança Regras Avançadas para cada varredura que este servidor executa, substituindo o padrão de configuração do Axe da sua organização — desde que seu administrador permita que os usuários alterem a configuração.

Os valores aceitos são "precise" (ou "90%"), "balanced" (ou "70%"), "thorough" (ou "50%") e "disabled". Os valores não são sensíveis a maiúsculas.

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

A ferramenta analyze também aceita um argumento advancedRules por chamada, que tem precedência sobre AXE_ADVANCED_RULES para essa chamada. Se o administrador bloquear a configuração, ambos são ignorados em favor do predefinido da organização. Veja Regras Avançadas para conhecer as regras completas de precedência e o bloco de resposta advancedRules.

AXE_SCREENSHOT_DIR

Define o diretório onde a ferramenta analyze grava capturas de tela quando uma chamada passa por screenshot.save sem um caminho explícito. Não tem efeito em chamadas que definem screenshot.saveTo, que sempre vence, e nenhum em chamadas que não salvam de forma alguma.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

Os caminhos relativos são resolvidos em relação ao diretório de trabalho do servidor. O padrão é o diretório temporário do seu sistema operacional.

Variáveis de atualização do token

Estas se aplicam apenas a OAuth 2.0 e permitem que um servidor em execução aceite um token de acesso recentemente atualizado para que uma sessão que dure mais que seu token não precise ser reiniciada. O ouvinte está desativado por padrão e só inicia quando ambos AXE_TOKEN_REFRESH_PORT e AXE_TOKEN_REFRESH_SECRET estão configurados.

Normalmente você não define estas manualmente. @deque/axe-auth run supervisiona o servidor e as fornece para você — você escolhe uma porta, e ele gera o segredo.

Seu token de atualização nunca é enviado ao servidor — apenas tokens de acesso de curta duração atravessam, e o segredo compartilhado é o que protege o endpoint. Veja Mantendo uma sessão longa ativa para configurações completas de Docker e npm.

IGT_TIMEOUT_MS

Delimita uma execução de Teste Guiado Inteligente, medida desde o momento em que o teste começa até o momento em que seus resultados retornam. Aplica-se tanto às chamadas analyze que passam igtTools quanto ao descontinuado ferramenta de igt.

Um teste é movido por IA e trabalha através dos elementos interativos da página um de cada vez, portanto, executa-se legitimamente por muito mais tempo do que uma varredura. Seu padrão é dimensionado para isso, e é por isso que é muito maior que BROWSER_TIMEOUT_MS. Uma execução que excede seu orçamento falha com um erro nomeando o orçamento que estourou:

IGT timed out after 200000ms

O erro também menciona a última etapa que o teste alcançou e quanto tempo atrás, o que indica se ainda estava progredindo ou se havia parado:

IGT timed out after 200000ms (last checkpoint: keyboard:tabstops:start 83s ago; last step: analyze-tabstops-ai 61s ago; last tick 2s ago)

Aumente IGT_TIMEOUT_MS quando uma página tiver elementos interativos suficientes para precisar de mais tempo. Aumentar BROWSER_TIMEOUT_MS não ajudará: cada tempo limite nesta página é seu próprio orçamento independente, e a varredura já havia terminado antes do teste começar.

{
  "env": {
    "IGT_TIMEOUT_MS": "400000"
  }
}

Variáveis de proxy

Se o tráfego de saída da sua rede precisar passar por um proxy, como o Zscaler, defina a URL completa do proxy e o servidor enviará todas as suas solicitações ao servidor axe através dele, incluindo inicialização, verificações de chave API e remediação.

Ortografias em minúsculas (https_proxy, http_proxy, no_proxy) também funcionam, e têm precedência quando ambas são definidas.

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NO_PROXY": "intranet.example.com"
  }
}

• O navegador de varredura usa o mesmo proxy das solicitações do servidor ao servidor axe. Liste todos os sites intranet que você vasculha em NO_PROXY.
• Distribuição npm: endereços locais (localhost, *.localhost, 127.0.0.0/8 e [::1]) sempre se conectam diretamente, então varreduras de servidores de desenvolvimento local não são afetadas.
• Distribuição Docker: o servidor reescreve URLs localhost para o endereço do host Docker (veja Varreduras de servidores de desenvolvimento local), que não é um endereço local dentro do container. Adicione esse endereço a NO_PROXY para que essas varreduras se conectem diretamente. O servidor registra o URL reescrito cada vez que escaneia uma página localhost, em Rewriting localhost URL using resolved IP of docker host.
• O navegador de varredura não pode usar um proxy que precise de um nome de usuário e senha. O servidor registra um aviso quando a URL do proxy inclui credenciais.
• A URL deve ser uma URL http:// ou https:// completa. Se o proxy que o servidor usa para AXE_SERVER_URL não for, o servidor para na inicialização com uma mensagem que nomeia a variável. Uma variável de proxy que o servidor não usa, como HTTP_PROXY com o servidor axe padrão https://, é ignorada.
• Se o proxy inspeciona o tráfego TLS, também defina NODE_EXTRA_CA_CERTS para o caminho do certificado CA do proxy.

Para a distribuição Docker, passe-os para o container com -e, da mesma forma que AXE_API_KEY.

Proxies com OAuth 2.0

Se você usar OAuth 2.0, o CLI @deque/axe-auth que faz o login e atualiza seus tokens também precisa do proxy. Defina NODE_USE_ENV_PROXY=1 junto com HTTPS_PROXY para que o Node.js envie suas solicitações através do proxy. Isto requer Node.js 22.21 ou superior.

Quando você iniciar o servidor através de axe-auth run, adicione-o ao mesmo bloco env:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NODE_USE_ENV_PROXY": "1"
  }
}

Quando você executar axe-auth login, defina as duas variáveis no mesmo terminal primeiro.

NODE_EXTRA_CA_CERTS

Defina NODE_EXTRA_CA_CERTS para o caminho de um arquivo PEM contendo o certificado CA da sua organização quando sua rede usa uma CA interna ou um proxy que inspeciona o tráfego TLS. O servidor o lê em todas as plataformas, então suas próprias solicitações ao servidor axe confiam nessa CA assim que o arquivo é analisado.

Se o navegador de varredura também confia na CA depende da sua plataforma:

• Docker — funciona automaticamente. Monte o certificado no container e aponte a variável para ele:

  {
    "mcpServers": {
      "axe-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "AXE_API_KEY",
          "-e",
          "NODE_EXTRA_CA_CERTS=/certs/ca.pem",
          "-v",
          "/path/to/your/ca.pem:/certs/ca.pem:ro",
          "dequesystems/axe-mcp-server"
        ],
        "env": {
          "AXE_API_KEY": "<your-api-key>"
        }
      }
    }
  }

• npm no Linux — funciona automaticamente uma vez que certutil esteja instalado (libnss3-tools no Debian/Ubuntu, nss-tools no RHEL/Fedora). Sem ele, o servidor inicia sem confiança do navegador e registra um aviso. A CA permanece confiada pelo Chromium naquela máquina após a saída do servidor.

• npm no macOS e Windows — adicione você mesmo a CA, ao seu chaveiro de login (macOS) ou ao seu armazenamento de Raízes Confiáveis do Usuário Atual (Windows), confiável apenas para SSL. O servidor registra qual armazenamento usar na inicialização.

No Linux e Docker, apenas o primeiro certificado no arquivo é adicionado ao navegador, então aponte NODE_EXTRA_CA_CERTS para a única CA à qual seus sites estão encadeados.

O servidor lê NODE_EXTRA_CA_CERTS apenas na inicialização, então reinicie-o após definir ou alterar a variável. Veja Certificados não confiáveis se as varreduras ainda falharem.

NODE_TLS_REJECT_UNAUTHORIZED

Definir NODE_TLS_REJECT_UNAUTHORIZED para "0" desliga as verificações de certificados tanto no servidor quanto no navegador de varredura. É um último recurso para quando NODE_EXTRA_CA_CERTS não é uma opção, como um teste local rápido contra um site com um certificado autoassinado.

{
  "env": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Para a distribuição Docker, passe isso para o container com -e NODE_TLS_REJECT_UNAUTHORIZED=0.

Variáveis de seleção faseada

Estas se aplicam a seleção faseada para o IGT de Elementos Interativos. A primeira chamada pausa a execução e mantém o navegador aberto até que seu agente faça a segunda chamada, assim esses valores limitam quanto tempo uma execução pausada espera e quantos navegadores podem permanecer abertos ao mesmo tempo.

Aumente SELECTION_SESSION_TTL_MS se você regularmente precisar de mais de três minutos para revisar uma longa lista de elementos. Ambos os valores devem ser inteiros positivos; caso contrário, o servidor se recusa a iniciar.

{
  "env": {
    "SELECTION_SESSION_TTL_MS": "600000"
  }
}

AXE_PAGE_LOAD_DELAY_MS

Ao contrário das variáveis acima, isso não é um tempo limite. É um atraso fixo que o servidor sempre espera após a conclusão da navegação, antes de executar qualquer ações de before e antes de fazer varreduras. Existe para páginas que continuam renderizando após o carregamento sem nada confiável para esperar. Cada varredura que este servidor executa paga o atraso na íntegra, então mantenha-o pequeno.

{
  "env": {
    "AXE_PAGE_LOAD_DELAY_MS": "2000"
  }
}

Prefira um etapa de waitFor no array de before da ferramenta de analyze onde você pode nomear um elemento que só existe após a página ter se estabilizado. waitFor continua no momento em que esse elemento aparece, sendo assim mais confiável e geralmente mais rápido do que um atraso geral.

Configurando Seu Agente de IA (Recomendado)

Para garantir que seu agente de codificação de IA usa corretamente as ferramentas do Axe MCP Server e segue as melhores práticas de acessibilidade, você pode fornecer instruções personalizadas. Essas instruções ajudam o agente a entender o fluxo de trabalho adequado para analisar e remediar problemas de acessibilidade.

Onde Adicionar Instruções

O método varia conforme o cliente:

• VS Code com GitHub Copilot - Adicione a .github/copilot-instructions.md na raiz do seu projeto
• Cursor - Adicione a "Cursor Rules" nas configurações
• Claude Code - Adicione a um arquivo CLAUDE.md na raiz do seu projeto
• Claude Desktop - Adicione às instruções personalizadas nas configurações
• Outros clientes MCP - Consulte a documentação do seu cliente para a configuração de instruções personalizadas

Exemplo de Instruções de Fluxo de Trabalho

Abaixo está um modelo recomendado que você pode adaptar para o seu agente:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. remediate → Pass ALL violations in one batched call to get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Por Que Isso Importa

Essas instruções garantem que seu agente:

• Use a expertise da Deque - Aproveita modelos de IA treinados em décadas de dados de avaliação de acessibilidade, em vez de um conhecimento geral de LLM
• Siga as melhores práticas - Aplica correções consistentes e compatíveis com WCAG em vez de soluções genéricas
• Verifica alterações - Sempre confirma se as correções realmente resolveram os problemas
• Evita falsa confiança - Não assume que sabe como corrigir problemas de acessibilidade sem orientação de especialistas

Embora opcionais, fornecer essas instruções melhora significativamente a qualidade e a confiabilidade das correções de acessibilidade em sua base de código.