Authenticatie

De axe MCP Server ondersteunt twee authenticatiemethoden. Beiden zijn beschikbaar voor alle gebruikers — kies degene die het beste bij uw workflow past:

• API-sleutel — een langlevende sleutel die gegenereerd is in het axe Account Portal. Het eenvoudigst om op te zetten.
• OAuth 2.0 — browser-gebaseerde login via de @deque/axe-auth CLI, met tokens die zijn opgeslagen in de sleutelhanger van je besturingssysteem en automatisch worden vernieuwd.

Je configureert de gekozen referentie in je client setup-gids. Elke setuppagina toont zowel de API-sleutel- als de OAuth-configuraties naast elkaar.

API-sleutel

1. Log in op de axe Accountportaal
2. Navigeer naar de API-sleutels pagina
3. Klik op NIEUWE API-SLEUTEL TOEVOEGEN
4. Selecteer axe MCP Server als het product
5. Voer een beschrijvende naam voor uw API-sleutel in
6. Klik op Opslaan
7. Kopieer de gegenereerde API-sleutel — je geeft deze door aan de server als de AXE_API_KEY-omgevingsvariabele

OAuth 2.0

OAuth 2.0 maakt gebruik van de Autorisatiecode Flow met PKCE en slaat tokens veilig op in uw OS-sleutelhanger, zodat u één keer authenticeert en de CLI de tokenvernieuwing automatisch uitvoert.

Authenticatie wordt beheerd door @deque/axe-auth, een zelfstandige CLI die je apart op je hostmachine installeert.

Vereisten

• Node.js 22.13.0 of nieuwer, wat @deque/axe-auth vereist (de npm-distributie van de server zelf heeft 22.19.0 of nieuwer nodig)
• Jouw gekozen axe MCP Server-distributie geïnstalleerd — zie Een Distributie Kiezen

Stap 1: Authenticeren

Voer het login-commando uit:

npx @deque/axe-auth login

De CLI zal:

1. Uw standaardbrowser openen naar de loginpagina
2. U vragen zich aan te melden met uw axe Account-inloggegevens
3. De resulterende tokens veilig opslaan in uw systeemsleutelhanger

Wanneer voltooid, bevestigt de terminal:

✓ Authenticated.

Je hoeft login slechts één keer per machine uit te voeren. Bij volgende oproepen vernieuwt npx @deque/axe-auth token je toegangstoken stilzwijgend met behulp van het opgeslagen vernieuwings-token.

Private cloud, niet-VS regio's, of lokale installaties

Als je organisatie een privécloud of een lokale axe-instantie gebruikt, geef dan de URL van je instantie door met --server (of stel de AXE_SERVER_URL-omgevingsvariabele in):

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

Stap 2: Uw cliënt configureren

Gebruik @deque/axe-auth token in je MCP-clientconfiguratie om een geldig toegangstoken in te voeren telkens wanneer de server start. Kies je client voor specifieke installatie-instructies:

• Installatie in VS Code met Copilot
• Installatie in Cursor
• Installatie in Claude Code

Elke installatiepagina bevat een OAuth-configuratiesectie naast de API-sleutelinstructies.

Sessies beheren

Token levensduur

OAuth-toegangstokens hebben een korte levensduur. Een configuratie die een token met @deque/axe-auth token injecteert, vangt het slechts één keer op, bij het opstarten van de server — dus een agent-sessie die langer duurt dan de levensduur van het token, zal authenticatiefouten gaan teruggeven.

Er zijn twee manieren om dit probleem aan te pakken:

• Aanbevolen — draai de server onder @deque/axe-auth run, wat ervoor zorgt dat het token automatisch voor de gehele sessie vers blijft.
• Anders — herstart de MCP-serververbinding in uw client. De configuratie voert @deque/axe-auth token opnieuw uit bij elke serverstart, wat een vers token ophaalt.

Een lange sessie in leven houden

@deque/axe-auth run start en superviseert de axe MCP Server, waarbij het toegangstoken wordt vernieuwd voordat het verloopt — zodat een sessie die uren duurt nooit het einde van het token bereikt, zonder herstart of handmatige stap.

Wijs uw MCP-client naar run als de serveropdracht in plaats van naar de server zelf, en geef de startopdracht door na --. Het beheert de levensduur van het serverproces zoals elke andere stdio-server.

npm-distributie:

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

Docker-distributie — publiceer de vernieuwingspoort op host-loopback, stuur de auth-variabelen door naar de container en verbind de luisteraar aan 0.0.0.0 erin:

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

Zie Token vernieuwen variabelen voor de server-side omgevingsvariabelen die betrokken zijn.

Uitloggen

Om uw tokens aan de serverkant in te trekken en ze uit de systeemsleutelhanger te verwijderen:

npx @deque/axe-auth logout

Als intrekking aan de serverzijde mislukt (bijvoorbeeld door een netwerkfout), worden lokale tokens nog steeds gewist en wordt een waarschuwing afgedrukt.

Opnieuw authenticeren

Als je vernieuwings-token is verlopen of is ingetrokken, beëindigt @deque/axe-auth token met code 1 en stuurt het je aan om opnieuw in te loggen. Voer npx @deque/axe-auth login opnieuw uit. Geef --force door om de bevestigingsprompt voor herauthenticatie over te slaan:

npx @deque/axe-auth login --force

Opdrachtreferentie

login

Opent een browser, voltooit de OAuth 2.0 Authorization Code + PKCE-procedure en slaat tokens op in de OS-sleutelhanger.

npx @deque/axe-auth login [options]

token

Drukt een momenteel geldig toegangstoken af naar stdout. Vernieuwt stilzwijgend als het opgeslagen token is verlopen. Beëindigt met code 1 als niet geauthenticeerd.

npx @deque/axe-auth token

logout

Trekt het opgeslagen vernieuwingtokens aan de serverzijde in en wist het lokale sleutelhangeritem.

npx @deque/axe-auth logout

run

Start en superviseert de axe MCP Server, houdt zijn toegangstoken vers voor de duur van de sessie. Configureer het als de serveropdracht van uw MCP-client in plaats van het handmatig aan te roepen. Zie Een lange sessie in leven houden.

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

Werkt met zowel de npm- als Docker-distributies, op macOS, Windows en Linux.

--help

Toont hulpinformatie voor @deque/axe-auth en zijn commando's.

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

Platformondersteuning

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

Probleemoplossing met OAuth

Browser opent niet automatisch

Als login geen browser kan openen, drukt het de autorisatie-URL af naar de terminal. Kopieer de URL en open deze handmatig om de authenticatie te voltooien.

Token verloopt tijdens lange sessies

Draai de server onder @deque/axe-auth run, wat het token voor u ververst en het probleem volledig oplost. Zonder dit, herstart de MCP-serververbinding in uw client om een vers token te verkrijgen. Zie Token levensduur hierboven.

„Niet geauthenticeerd“ fout van token

Je sessie is verlopen of tokens zijn gewist. Voer npx @deque/axe-auth login opnieuw uit om opnieuw te authenticeren.

Fouten bij MCP-serverauthenticatie

• Bevestig dat alleen AXE_ACCESS_TOKEN is ingesteld (niet AXE_API_KEY)
• Bevestig dat AXE_SERVER_URL overeenkomt met je axe-instantie-URL — dit moet dezelfde URL zijn die bij --server tijdens het inloggen is gebruikt (of https://axe.deque.com als je de standaard gebruikte)
• Voer npx @deque/axe-auth token direct uit in je terminal om te bevestigen dat je een geldig token hebt
• Als het beëindigt met code 1, herauthenticeer met npx @deque/axe-auth login

Linux-sleutelhanger niet beschikbaar

Zie de Platformondersteuning roeptekst hierboven.