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

• Un versione attiva di Node.js LTS
• 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 durata breve. Se una sessione dura più della vita del token, il server restituirà errori di autenticazione.

Soluzione alternativa: Riavvia la connessione al server MCP nel tuo client. La configurazione riesegue @deque/axe-auth token a ogni avvio del server, il quale recupera automaticamente un nuovo token.

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

--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

Vedi Durata del token sopra. Riavvia la connessione al server MCP nel tuo client per ottenere un nuovo token.

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.