Configuração no Claude Code
Prefere uma configuração com um comando? O plugin de Acessibilidade axe registra o servidor para você e adiciona habilidades e comandos de barra que conduzem o fluxo de trabalho analisar → remediar → verificar. Esta página cobre a configuração do servidor manualmente.
Antes de configurar, escolha uma distribuição (Docker ou npm) e configure a autenticação (chave API ou OAuth 2.0). Em seguida, adicione a configuração correspondente abaixo.
O servidor Axe MCP pode ser adicionado tanto no nível do projeto quanto no nível do usuário:
- Nível de projeto: Crie um arquivo em
.mcp.jsonno diretório raiz do seu projeto (melhor para compartilhar configurações com uma equipe) - Nível de usuário: Adicione o servidor ao objeto
mcpServersem~/.claude.jsonno seu diretório pessoal (aplica-se a todos os seus projetos). Você também pode gerenciar servidores a nível de usuário com o comandoclaude mcp add --scope user— veja Claude Code MCP para mais detalhes.
Se você já tiver outros servidores definidos, adicione o bloco axe-mcp-server dentro do objeto mcpServers existente.
Docker
Chave de API
{
"mcpServers": {
"axe-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--add-host=host.docker.internal:host-gateway",
"-i",
"--rm",
"-e",
"AXE_SERVER_URL",
"-e",
"AXE_API_KEY",
"dequesystems/axe-mcp-server:latest"
],
"env": {
"AXE_SERVER_URL": "https://axe.deque.com",
"AXE_API_KEY": "${AXE_API_KEY}"
}
}
}
}A configuração usa "AXE_API_KEY": "${AXE_API_KEY}" para manipulação segura de entrada. A sintaxe ${AXE_API_KEY} instrui o Claude Code a puxar o valor do seu ambiente shell. Para mais informações, veja Claude Code MCP.
Defina sua chave de API como uma variável de ambiente no seu shell:
export AXE_API_KEY="your-api-key-here"Para configuração permanente, adicione esta linha ao seu perfil de shell (~/.bashrc, ~/.zshrc, etc.).
Usando uma instância regional, nuvem privada ou axe local? Atualize o valor AXE_SERVER_URL no bloco env com o URL base da sua instância:
"env": {
"AXE_API_KEY": "${AXE_API_KEY}",
"AXE_SERVER_URL": "https://your-axe-instance.example.com"
}Se omitido, o servidor assume como padrão https://axe.deque.com (instância SaaS compartilhada dos EUA da Deque). Veja Referência de Configuração para mais detalhes.
OAuth 2.0
Antes de configurar, complete Etapa 1: Autenticar no guia de Autenticação.
Inicie o servidor através de @deque/axe-auth run, que mantém o token de acesso do servidor em execução atualizado enquanto a sessão durar.
{
"mcpServers": {
"axe-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@deque/axe-auth",
"run",
"--",
"docker",
"run",
"--add-host=host.docker.internal:host-gateway",
"-i",
"--rm",
"-p",
"127.0.0.1:9223:9223",
"-e",
"AXE_ACCESS_TOKEN",
"-e",
"AXE_TOKEN_REFRESH_PORT",
"-e",
"AXE_TOKEN_REFRESH_SECRET",
"-e",
"AXE_TOKEN_REFRESH_HOST=0.0.0.0",
"dequesystems/axe-mcp-server:latest"
],
"env": {
"AXE_TOKEN_REFRESH_PORT": "9223"
}
}
}
}A atualização do token chegou ao servidor axe MCP em v1.5.0. npx -y @deque/axe-auth sempre busca o CLI atual, mas uma imagem Docker puxada antes dessa versão não tem um ouvinte de atualização para run enviar — obtenha-a novamente com docker pull dequesystems/axe-mcp-server:latest.
npx -y @deque/axe-auth run inicia o contêiner e o supervisiona durante a sessão, enviando um token de acesso recém-gerado para o servidor em execução antes que o atual expire. Seu token de atualização nunca sai da sua máquina — apenas tokens de acesso de curta duração chegam ao servidor. A flag -y pula o prompt "Ok para prosseguir?" que npx normalmente perguntaria em um shell não interativo.
As flags restantes existem para tornar essa transmissão acessível dentro do contêiner:
-p 127.0.0.1:9223:9223publica o ouvinte de atualização do servidor apenas no host loopback, mantendo-o fora das interfaces externas da sua máquina.-e AXE_ACCESS_TOKEN,-e AXE_TOKEN_REFRESH_PORTe-e AXE_TOKEN_REFRESH_SECRETencaminham os valores querungera para dentro do contêiner. Passe apenas os nomes, sem=value—runos fornece.-e AXE_TOKEN_REFRESH_HOST=0.0.0.0vincula o ouvinte à interface de rede do contêiner. Uma porta publicada reencaminha para lá em vez de para o loopback do contêiner, então o vínculo padrão ao loopback ficaria inacessível. O segredo compartilhado, e não o isolamento do contêiner, é o que protege o endpoint.
9223 é um exemplo — qualquer porta livre na sua máquina funciona, desde que AXE_TOKEN_REFRESH_PORT e o -p publicado nomeiem a mesma. Veja Variáveis de atualização de token para a referência completa.
Usando uma instância regional, privada, em nuvem ou local do axe? Adicione AXE_SERVER_URL ao comando Docker e ao bloco env, junto com a porta de atualização:
"args": [
"-y",
"@deque/axe-auth",
"run",
"--",
"docker",
"run",
"--add-host=host.docker.internal:host-gateway",
"-i",
"--rm",
"-p",
"127.0.0.1:9223:9223",
"-e",
"AXE_SERVER_URL",
"-e",
"AXE_ACCESS_TOKEN",
"-e",
"AXE_TOKEN_REFRESH_PORT",
"-e",
"AXE_TOKEN_REFRESH_SECRET",
"-e",
"AXE_TOKEN_REFRESH_HOST=0.0.0.0",
"dequesystems/axe-mcp-server:latest"
],
"env": {
"AXE_TOKEN_REFRESH_PORT": "9223",
"AXE_SERVER_URL": "https://your-axe-instance.example.com"
}Use o mesmo URL que você passou para --server ao fazer login, assim os tokens que axe-auth emite vêm da instância que o servidor chama. Se omitido, o servidor usa por padrão https://axe.deque.com (a instância SaaS compartilhada dos EUA da Deque). Veja Referência de Configuração para mais detalhes.
npm
A distribuição npm é executada no Node.js. Use uma versão LTS ativa do Node.js — versões mais antigas podem não ser suportadas.
A distribuição npm necessita de um navegador Chromium — instale um via Playwright ou aponte para um binário existente. Veja Escolhendo uma Distribuição.
Chave de API
{
"mcpServers": {
"axe-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "axe-mcp-server"],
"env": {
"AXE_API_KEY": "${AXE_API_KEY}"
}
}
}
}Configure AXE_API_KEY no seu shell conforme mostrado acima para que o Claude Code possa puxá-lo do ambiente.
OAuth 2.0
OAuth 2.0 também é suportado com a distribuição npm. Envolva o servidor em @deque/axe-auth run exatamente como acima — não há um contêiner para publicar uma porta, então o comando é mais curto:
{
"mcpServers": {
"axe-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@deque/axe-auth",
"run",
"--",
"npx",
"-y",
"axe-mcp-server"
],
"env": {
"AXE_TOKEN_REFRESH_PORT": "9223"
}
}
}
}npx -y @deque/axe-auth run inicia o servidor e o supervisiona durante toda a sessão, enviando um token de acesso recém-gerado para o processo em execução antes que o atual expire. Não é necessário publicar a porta aqui: o processo encapsulado herda AXE_TOKEN_REFRESH_PORT diretamente e o ouvinte permanece no loopback. 9223 é um exemplo — qualquer porta livre em sua máquina funciona, e a variável é opcional aqui: omita-a e run escolhe uma porta livre para a sessão.
Diferente de um contêiner, a distribuição npm herda todo o ambiente do seu shell. Se AXE_API_KEY for exportado lá, ele chega ao servidor junto com o token OAuth e o servidor se recusa a iniciar. Desfaça essa configuração no shell do qual você inicia seu editor, ou use a configuração Docker acima, que apenas recebe as variáveis passadas com flags explícitas -e.
Consulte Autenticação para o fluxo completo.
Defina ou AXE_API_KEY ou AXE_ACCESS_TOKEN — não ambos. O servidor falhará ao iniciar se ambas as variáveis estiverem definidas.
Uso e verificação
Uma vez configurado, reinicie o Claude Code para carregar o servidor MCP.
- Inicie o Claude Code a partir do seu terminal:
claude - Digite
/mcppara gerenciar conexões do servidor MCP - Você deve ver
axe-mcp-serverlistado com as ferramentasanalyze,remediateeigtdisponíveis
Configurando o Claude Code (recomendado)
Para garantir que o Claude Code use corretamente as ferramentas do servidor MCP da axe, adicione as instruções recomendadas de fluxo de trabalho de análise e remediação a um arquivo CLAUDE.md no raiz do seu projeto. Veja Configurando Seu Agente de IA para o modelo completo.