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 di axe. La più semplice da configurare.
• OAuth 2.0 — login basato su browser via la @deque/axe-auth CLI, con token memorizzati nel portachiavi del tuo sistema operativo e rinnovati automaticamente.

Configura la credenziale scelta nella tua guida alla configurazione del client. Ogni pagina di configurazione mostra sia le configurazioni della chiave API che dell'OAuth affiancate.

Chiave API

1. Accedi al Portale Account di axe
2. Vai alla 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 passerai al server come AXE_API_KEY variabile di ambiente

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, una CLI indipendente che installi separatamente sulla tua macchina host.

Prerequisiti

• Una versione attiva di Node.js LTS
• La tua distribuzione scelta del server MCP di axe installata — vedere 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 il token di accesso silenziosamente 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 on-premises di axe, passa l'URL della tua istanza con --server (o imposta la AXE_SERVER_URL variabile d'ambiente):

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 client MCP per inserire 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 del server MCP nel tuo client. La configurazione viene eseguita di nuovo @deque/axe-auth token ad ogni avvio del server, il che 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 esce con codice 1 e ti indirizza a effettuare nuovamente il login. Esegui npx @deque/axe-auth login di nuovo. Passa --force per saltare il prompt di conferma della 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 attualmente valido su stdout. Aggiorna silenziosamente se il token memorizzato è scaduto. Esce con 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 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 di nuovo 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 usato con --server durante il login (o https://axe.deque.com se hai usato il predefinito)
• Esegui npx @deque/axe-auth token direttamente nel tuo terminale per confermare di avere un token valido
• Se esce con codice 1, ri-autenticati con npx @deque/axe-auth login

Portachiavi Linux non disponibile

Vedi il Supporto della piattaforma sopra.