Autenticação

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

O servidor axe MCP suporta dois métodos de autenticação. Ambos estão disponíveis para todos os usuários — escolha o que melhor se adapta ao seu fluxo de trabalho:

  • Chave de API — uma chave de longa duração gerada no Portal de Contas do axe. Mais fácil de configurar.
  • OAuth 2.0 — login via navegador através da CLI @deque/axe-auth, com tokens armazenados na chave de segurança do seu SO e atualizados automaticamente.

Você configura a credencial escolhida no seu guia de configuração do cliente. Cada página de configuração mostra as configurações de chave da API e OAuth lado a lado.

note

Defina ou AXE_API_KEY ou AXE_ACCESS_TOKEN — não ambos. O servidor falhará ao iniciar se ambas as variáveis estiverem definidas.

Chave de API

  1. Faça login no Portal de Contas do axe
  2. Navegue até o página de Chaves de API
  3. Clique em ADICIONAR NOVA CHAVE DE API
  4. Selecione axe MCP Server como o produto
  5. Digite um nome descritivo para sua chave de API
  6. Clique em Salvar
  7. Copie a chave da API gerada — você a passará para o servidor como a variável de ambiente AXE_API_KEY

OAuth 2.0

OAuth 2.0 usa o Authorization Code Flow com PKCE e armazena tokens de forma segura no keychain do seu SO, para que você autentique uma vez e o CLI gerencie a atualização de tokens automaticamente.

A autenticação é gerida por @deque/axe-auth, uma CLI independente que você instala separadamente na sua máquina host.

Pré-requisitos

  • Node.js versão 22.13.0 ou posterior, que @deque/axe-auth requer (a distribuição npm do próprio servidor necessita da versão 22.19.0 ou posterior)
  • Sua distribuição escolhida do servidor axe MCP instalada — veja Escolhendo uma Distribuição

Passo 1: Autenticar

Execute o comando de login:

npx @deque/axe-auth login

O CLI irá:

  1. Abrir seu navegador padrão na página de login
  2. Solicitar que você faça login com suas credenciais de Conta do axe
  3. Armazenar os tokens resultantes de forma segura no keychain do seu sistema
note

Seu sistema operacional pode solicitar que você conceda acesso ao keychain a primeira vez que os tokens forem armazenados.

Quando concluir, o terminal confirma:

✓ Authenticated.

Você só precisa executar login uma vez por máquina. Em chamadas subsequentes, npx @deque/axe-auth token atualiza seu token de acesso silenciosamente usando o token de atualização armazenado.

Nuvem privada, regiões fora dos EUA, ou instalações no local

Se sua organização utiliza uma instância privada ou local do axe, passe a URL da sua instância com --server (ou configure a variável de ambiente AXE_SERVER_URL):

npx @deque/axe-auth login --server https://your-axe-instance.example.com

Passo 2: Configure seu cliente

Use @deque/axe-auth token na configuração do seu cliente MCP para injetar um token de acesso válido cada vez que o servidor inicia. Escolha o seu cliente para instruções específicas de configuração:

Cada página de configuração inclui uma seção de configuração OAuth juntamente com as instruções de chave API.

Gerenciando sessões

Duração do token

Os tokens de acesso OAuth têm curta duração. Uma configuração que injeta um token com @deque/axe-auth token captura-o uma vez, no início do servidor — então, uma sessão de agente que dura mais que o tempo de vida do token começará a retornar erros de autenticação.

Existem duas maneiras de lidar com isso:

  • Recomendado — execute o servidor sob @deque/axe-auth run, que mantém o token atualizado para toda a sessão automaticamente.
  • Caso contrário — reinicie a conexão do servidor MCP no seu cliente. A configuração executa novamente @deque/axe-auth token a cada início do servidor, o que obtém um token novo.

Mantendo uma sessão longa ativa

@deque/axe-auth run lança e supervisiona o servidor MCP axe, renovando seu token de acesso antes que expire — assim, uma sessão que dura horas nunca ocorre a expiração do token, sem reinício e sem passos manuais.

Direcione seu cliente MCP para run como o comando do servidor em vez do próprio servidor, e passe o comando de inicialização após --. Ele gerencia a vida útil do processo do servidor como qualquer outro servidor stdio.

Distribuição npm:

{
  "command": "npx",
  "args": ["-y", "@deque/axe-auth", "run", "--", "npx", "axe-mcp-server"],
  "env": {
    "AXE_TOKEN_REFRESH_PORT": "9223"
  }
}

Distribuição Docker — publique a porta de renovação na interface de loopback do host, encaminhe as variáveis de autenticação para o contêiner e vincule o listener a 0.0.0.0 dentro dele:

{
  "command": "npx",
  "args": [
    "-y",
    "@deque/axe-auth",
    "run",
    "--",
    "docker",
    "run",
    "-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"
  }
}
important

AXE_TOKEN_REFRESH_HOST=0.0.0.0 é necessário sob Docker. Uma porta publicada reencaminha para a interface de rede do contêiner, não para seu loopback, então a vinculação padrão de loopback seria inacessível. Publicar como 127.0.0.1:9223:9223 mantém o endpoint fora das interfaces externas do seu host, e o segredo compartilhado — não o isolamento do contêiner — é o que protege o próprio endpoint.

note

Seu token de renovação nunca sai da sua máquina. Apenas tokens de acesso de curta duração são enviados para o servidor, por meio de uma conexão de loopback autenticada por um segredo compartilhado que run gera para a sessão. Esta é a mesma propriedade de isolamento que mantém o token de renovação fora do contêiner.

Veja Variáveis de token de renovação para as variáveis de ambiente do lado do servidor envolvidas.

Desconectando

Para revogar seus tokens do lado do servidor e removê-los do chaveiro do sistema:

npx @deque/axe-auth logout

Se a revogação do lado do servidor falhar (por exemplo, devido a um erro de rede), os tokens locais ainda serão removidos e um aviso será impresso.

Reautenticando

Se seu token de atualização expirou ou foi revogado, @deque/axe-auth token sai com o código 1 e orienta você a fazer login novamente. Execute npx @deque/axe-auth login novamente. Passe --force para pular o prompt de confirmação de reautenticação:

npx @deque/axe-auth login --force

Referência de comando

login

Abre um navegador, completa o fluxo OAuth 2.0 de Código de Autorização + PKCE, e preserva tokens no chaveiro do sistema operacional.

npx @deque/axe-auth login [options]
Flag Descrição
--server <url> URL base da sua instância do axe. O padrão é https://axe.deque.com. Necessária apenas para nuvens privadas, regiões fora dos EUA ou instalações locais.
--force Pular confirmação de reautenticação quando já estiver logado.
--allow-insecure-issuer Permitir URLs http não-loopback (o padrão é apenas https; http loopback é sempre permitido). Aplica-se apenas a login; token e logout usam a política persistida no login.
--no-allow-insecure-issuer Forçar allowInsecureIssuer=false para o novo login (e a entrada que ele persiste). Mutuamente exclusivo com --allow-insecure-issuer. token e logout ignoram esta opção.

token

Imprime um token de acesso atualmente válido no stdout. Atualiza silenciosamente se o token armazenado estiver expirado. Sai com o código 1 se não estiver autenticado.

npx @deque/axe-auth token

logout

Revoga o token de atualização armazenado no lado do servidor e limpa a entrada local do chaveiro.

npx @deque/axe-auth logout

run

Lança e supervisiona o servidor MCP axe, mantendo seu token de acesso atualizado durante toda a sessão. Configure-o como o comando do servidor do seu cliente MCP em vez de invocá-lo manualmente. Veja Mantendo uma sessão longa ativa.

npx @deque/axe-auth run [options] -- <server launch command>
Flag Descrição
--port <port> Porta de loopback usada para enviar tokens renovados para o servidor. Equivalente a AXE_TOKEN_REFRESH_PORT. Opcional na distribuição npm: sem uma, run escolhe uma porta livre para a sessão. Necessária quando o comando encapsulado é um runtime de contêiner (docker, podman ou nerdctl), que só pode acessar uma porta que você publica — run recusa aqueles sem uma porta fixa.
--secret <secret> Segredo compartilhado autenticando cada envio. Equivalente a AXE_TOKEN_REFRESH_SECRET. Gerado automaticamente a menos que você fixe um valor.

Funciona tanto com as distribuições npm quanto Docker, em macOS, Windows e Linux.

--help

Exibe informações de ajuda para @deque/axe-auth e seus comandos.

npx @deque/axe-auth --help
npx @deque/axe-auth <command> --help

Suporte à plataforma

Plataforma Armazenamento de Token
macOS Chaveiro do macOS
Windows Gerenciador de Credenciais do Windows
Linux D-Bus Secret Service (GNOME Keyring, KWallet, etc.)
caution

Linux: @deque/axe-auth requer um D-Bus Secret Service funcional. Ambientes headless ou de desktop mínimo podem não ter um disponível. Se você vir um erro como:

System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).

peça ao administrador do sistema para configurar o GNOME Keyring ou um provedor de Secret Service compatível.

Resolução de problemas OAuth

O navegador não abre automaticamente

Se login não puder abrir um navegador, ele imprimirá a URL de autorização no terminal. Copie a URL e abra-a manualmente para completar a autenticação.

Expiração de token durante longas sessões

Execute o servidor sob @deque/axe-auth run, que renova o token para você e elimina completamente o problema. Sem isso, reinicie a conexão do servidor MCP no seu cliente para obter um token novo. Veja Duração do token acima.

Erro de "Não autenticado" de token

Sua sessão expirou ou os tokens foram limpos. Execute npx @deque/axe-auth login novamente para reautenticar.

Erros de autenticação do servidor MCP

  • Confirme que apenas AXE_ACCESS_TOKEN está configurado (não AXE_API_KEY)
  • Confirme que AXE_SERVER_URL corresponde à URL da sua instância do axe — esta deve ser a mesma URL usada com --server durante o login (ou https://axe.deque.com se você usou o padrão)
  • Execute npx @deque/axe-auth token diretamente no seu terminal para confirmar que você tem um token válido
  • Se sair com o código 1, reautentique com npx @deque/axe-auth login

Cadeia de chaves do Linux indisponível

Veja o aviso Suporte da Plataforma acima.

Is this page helpful?

Help us improve this page

Still need help?