Autenticazione

Il server MCP di axe supporta due metodi di autenticazione. Entrambi sono disponibili per tutti gli utenti — scegli quello che si adatta meglio al tuo flusso di lavoro:

• Chiave API — una chiave a lunga durata generata nel portale account axe. Il più semplice da configurare.
• OAuth 2.0 — accesso basato su browser tramite il @deque/axe-auth CLI, con i token memorizzati nel portachiavi del sistema operativo e aggiornati automaticamente.

Configuri la credenziale scelta nel tuo guida alla configurazione del client. Ogni pagina di configurazione mostra affiancate le configurazioni per la chiave API e OAuth.

Chiave API

1. Accedi al Portale Account di axe
2. Vai al pagina API Keys
3. Clicca AGGIUNGI NUOVA CHIAVE API
4. Seleziona axe MCP Server come prodotto
5. Inserisci un nome descrittivo per la tua chiave API
6. Clicca Salva
7. Copia la chiave API generata — la trasmetterai al server come variabile d'ambiente AXE_API_KEY

OAuth 2.0

OAuth 2.0 utilizza il flusso Authorization Code con PKCE e memorizza i token in modo sicuro nel portachiavi del tuo sistema operativo, quindi ti autentichi una volta e la CLI gestisce automaticamente il rinnovo del token.

L'autenticazione è gestita da @deque/axe-auth, un CLI standalone che si installa separatamente sulla macchina host.

Prerequisiti

• Node.js 22.13.0 o successiva, che @deque/axe-auth richiede (la distribuzione npm del server stesso necessita di almeno la versione 22.19.0)
• La distribuzione del server axe MCP che hai scelto installata — vedi Scegliere una Distribuzione

Passo 1: Autenticazione

Esegui il comando di login:

npx @deque/axe-auth login

La CLI:

1. Apre il browser predefinito sulla pagina di login
2. Ti richiede di accedere con le tue credenziali dell'Account di axe
3. Memorizza i token risultanti nel portachiavi del tuo sistema in modo sicuro

Al termine, il terminale conferma:

✓ Authenticated.

Devi eseguire login solo una volta per macchina. Alle invocazioni successive, npx @deque/axe-auth token aggiorna silenziosamente il token di accesso utilizzando il token di aggiornamento memorizzato.

Cloud privato, regioni non-US o installazioni on-premises

Se la tua organizzazione utilizza un cloud privato o un'istanza axe on-premises, trasmetti l'URL dell'istanza con --server (o imposta la variabile ambientale AXE_SERVER_URL):

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

Passo 2: Configura il tuo client

Usa @deque/axe-auth token nella configurazione del tuo client MCP per iniettare un token di accesso valido ogni volta che il server si avvia. Scegli il tuo client per istruzioni specifiche sulla configurazione:

• Configurazione in VS Code con Copilot
• Configurazione in Cursor
• Configurazione in Claude Code

Ogni pagina di configurazione include una sezione sulla configurazione OAuth insieme alle istruzioni sulla chiave API.

Gestione delle sessioni

Durata del token

I token di accesso OAuth hanno una breve durata. Una configurazione che inietta un token con @deque/axe-auth token lo cattura una sola volta, all'avvio del server — quindi una sessione dell'agente che dura più a lungo della durata del token comincerà a restituire errori di autenticazione.

Ci sono due modi per gestire questa situazione:

• Consigliato — eseguire il server sotto @deque/axe-auth run, che mantiene automaticamente fresco il token per l'intera sessione.
• Altrimenti — riavviare la connessione del server MCP nel tuo client. La configurazione riesegue @deque/axe-auth token a ogni avvio del server, ottenendo un nuovo token.

Mantenere viva una sessione lunga

@deque/axe-auth run lancia e supervisiona il server MCP di axe, aggiornando il suo token di accesso prima che scada — in modo che una sessione che dura ore non incontri mai la scadenza del token, senza riavvii o interventi manuali.

Configura il tuo client MCP per puntare a run come comando del server anziché al server stesso, e passa il comando di avvio dopo --. Gestisce la durata del processo del server come qualsiasi altro server stdio.

Distribuzione npm:

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

Distribuzione Docker — pubblica la porta di refresh su loopback host, inoltra le variabili di autenticazione nel container e collega il listener a 0.0.0.0 al suo interno:

{
  "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"
  }
}

Vedi Variabili di token refresh per le variabili d'ambiente lato server coinvolte.

Disconnessione

Per revocare i tuoi token lato server e cancellarli dal portachiavi di sistema:

npx @deque/axe-auth logout

Se la revoca lato server fallisce (ad esempio, a causa di un errore di rete), i token locali vengono comunque cancellati e viene stampato un avviso.

Ri-autenticazione

Se il tuo token di aggiornamento è scaduto o è stato revocato, @deque/axe-auth token termina con codice 1 e ti indirizza a effettuare nuovamente il login. Esegui nuovamente npx @deque/axe-auth login. Trasmetti --force per saltare la richiesta di conferma di ri-autenticazione:

npx @deque/axe-auth login --force

Riferimenti ai comandi

login

Apre un browser, completa il flusso di Autorizzazione OAuth 2.0 + PKCE e salva i token nel portachiavi del sistema operativo.

npx @deque/axe-auth login [options]

token

Stampa un token di accesso valido attualmente su stdout. Aggiorna silenziosamente se il token memorizzato è scaduto. Termina con il codice 1 se non autenticato.

npx @deque/axe-auth token

logout

Revoca il token di aggiornamento salvato sul lato server e cancella l'entrata nel portachiavi locale.

npx @deque/axe-auth logout

run

Lancia e supervisiona il server MCP di axe, mantenendo fresco il suo token di accesso per tutta la durata della sessione. Configuralo come comando del server del tuo client MCP piuttosto che invocarlo manualmente. Vedi Mantenere viva una sessione lunga.

npx @deque/axe-auth run [options] -- <server launch command>

Funziona con entrambe le distribuzioni npm e Docker, su macOS, Windows e Linux.

--help

Mostra le informazioni di aiuto per @deque/axe-auth e i suoi comandi.

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

Supporto della piattaforma

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

Risoluzione dei problemi di OAuth

Il browser non si apre automaticamente

Se login non può aprire un browser, stampa l'URL di autorizzazione sul terminale. Copia l'URL e aprilo manualmente per completare l'autenticazione.

Scadenza del token durante sessioni lunghe

Esegui il server sotto @deque/axe-auth run, che aggiorna il token per te e rimuove il problema completamente. Senza di esso, riavvia la connessione del server MCP nel tuo client per ottenere un nuovo token. Vedi Durata del token sopra.

Errore "Non autenticato" da token

La tua sessione è scaduta o i token sono stati cancellati. Esegui nuovamente npx @deque/axe-auth login per ri-autenticarti.

Errori di autenticazione del server MCP

• Conferma che solo AXE_ACCESS_TOKEN è impostato (non AXE_API_KEY)
• Conferma che AXE_SERVER_URL corrisponde all'URL della tua istanza axe — questo dovrebbe essere lo stesso URL utilizzato con --server durante il login (o https://axe.deque.com se hai utilizzato il default)
• Esegui npx @deque/axe-auth token direttamente nel tuo terminale per confermare di avere un token valido
• Se termina con codice 1, ri-autenticati con npx @deque/axe-auth login

Portachiavi Linux non disponibile

Vedi il box Supporto della piattaforma sopra.