Configuratie Referentie

Deze pagina documenteert de omgevingsvariabelen die de Axe MCP Server leest, en de aanbevolen aangepaste instructies voor uw AI-agent. Deze zijn van toepassing op zowel de Docker- en npm-distributies. Voor waar deze waarden te plaatsen, zie uw handleiding voor het instellen van de client.

Configuratieopties

De Axe MCP Server ondersteunt verschillende omgevingsvariabelen voor aanpassing:

AXE_SERVER_URL

De standaardwaarde (https://axe.deque.com) is correct voor de meeste gebruikers — degenen op Deque's gedeelde US SaaS-instantie. Als uw organisatie een van de volgende gebruikt, moet u AXE_SERVER_URL instellen op de basis-URL van uw instantie:

• Een regionale SaaS-instantie (EU, Australië, Frankfurt, enz.)
• Een private cloud-implementatie
• Een on-premises-installatie

Als u niet zeker weet welk exemplaar uw organisatie gebruikt, controleer dan de URL die u gebruikt om in te loggen op het Axe Account Portal, of vraag het aan uw beheerder.

Stel AXE_SERVER_URL expliciet in binnen het env-blok van uw MCP-serverconfiguratie. De handleidingen voor clientsetup omvatten voorbeelden die precies laten zien waar het moet worden toegevoegd.

AXE_CHROME_PATH

alleen npm-distributie. Dit wordt niet ondersteund in Docker, dat altijd de meegeleverde browser gebruikt — de server start niet als AXE_CHROME_PATH is ingesteld onder de Docker-distributie.

Standaard gebruikt de npm-distributie de Chromium-build die u installeert via Playwright. Stel AXE_CHROME_PATH in op het volledige pad van een bestaande Chrome/Chromium-binary om die in plaats daarvan te gebruiken en de installatie van Playwright over te slaan.

• De waarde moet een uitvoerbaar binair bestand zijn, geen .app-bundel of directory. Wijs op macOS bijvoorbeeld naar de binary binnen de bundel: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• Het binaire bestand moet bestaan en op macOS en Linux starten en reageren op --version. De server controleert dit bij het opstarten en, als dat niet lukt, stopt met een bericht dat uitlegt waarom, zoals het bestand dat niet uitvoerbaar is of een ontbrekende systeembibliotheek. Op Windows controleert de server alleen of het bestand bestaat, dus een binair bestand dat niet kan starten, faalt wanneer de eerste scan begint.
• Branded Google Chrome stabiel 137 en later wordt niet ondersteund. Gebruik Chrome voor testen of een andere Chromium-compatibele binary.

De analyze en igt tools accepteren ook een per-oproep chromePath-argument, dat voorrang heeft boven AXE_CHROME_PATH voor die oproep.

AXE_ADVANCED_RULES

Stelt de Geavanceerde regels-vertrouwensvoorinstelling in voor elke scan die deze server uitvoert, waarbij de standaard Axe-configuratie van uw organisatie wordt overschreven — mits uw beheerder gebruikers toestaat de instelling te wijzigen.

Geaccepteerde waarden zijn "precise" (of "90%"), "balanced" (of "70%"), "thorough" (of "50%"), en "disabled". Waarden zijn niet hoofdlettergevoelig.

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

De analyze tool accepteert ook een per-aanroep advancedRules argument, dat voorrang heeft boven AXE_ADVANCED_RULES voor die oproep. Als uw beheerder de instelling heeft vergrendeld, worden beide genegeerd ten gunste van de preset van de organisatie. Zie Geavanceerde regels voor de volledige voorrangsregels en het advancedRules antwoordblok.

AXE_SCREENSHOT_DIR

Stelt de directory in waarin de analyze tool schermopnamen opslaat wanneer een oproep screenshot.save doorgeeft zonder een expliciet pad. Het heeft geen effect op oproepen die screenshot.saveTo instellen, welke altijd winnen, en geen effect op oproepen die helemaal niet opslaan.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

Relatieve paden worden opgelost ten opzichte van de werkdirectory van de server. De standaard is de tijdelijke directory van uw besturingssysteem.

Token vernieuwingsvariabelen

Deze gelden alleen voor OAuth 2.0 en laten een draaiende server een nieuw-verversede toegangstoken accepteren, zodat een sessie die langer duurt dan zijn token geen herstart nodig heeft. De listener is standaard uitgeschakeld en start alleen wanneer zowel AXE_TOKEN_REFRESH_PORT als AXE_TOKEN_REFRESH_SECRET zijn ingesteld.

Normaal stelt u deze niet handmatig in. @deque/axe-auth run houdt toezicht op de server en levert ze voor u - u kiest een poort, en hij genereert het geheim.

Uw verversingstoken wordt nooit naar de server gestuurd — alleen kortlevende toegangstokens worden verzonden, en het gedeelde geheim is wat het eindpunt beschermt. Zie Een lange sessie in leven houden voor volledige Docker- en npm-configuraties.

IGT_TIMEOUT_MS

Beperkt één Intelligent Guided Test run, gemeten vanaf het moment dat de test start tot het moment dat de resultaten terugkomen. Het geldt zowel voor analyze oproepen die igtTools doorgeven als voor de verouderde igt hulpmiddel.

Een test is AI-aangedreven en werkt één voor één door de interactieve elementen van de pagina, dus het draait terecht veel langer dan een scan. De standaardwaarde is daarop berekend, en daarom is het veel groter dan BROWSER_TIMEOUT_MS. Een run die zijn budget overschrijdt, eindigt met een foutmelding die het overschreden budget noemt:

IGT timed out after 200000ms

De fout vermeldt ook de laatste stap die de test heeft bereikt en hoe lang geleden, wat aangeeft of er nog voortgang werd gemaakt of gestopt:

IGT timed out after 200000ms (last checkpoint: keyboard:tabstops:start 83s ago; last step: analyze-tabstops-ai 61s ago; last tick 2s ago)

Verhoog IGT_TIMEOUT_MS wanneer een pagina genoeg interactieve elementen heeft om extra tijd nodig te hebben. Het verhogen van BROWSER_TIMEOUT_MS helpt niet: elke time-out op deze pagina is een eigen onafhankelijk budget en de scan was al voltooid voordat de test startte.

{
  "env": {
    "IGT_TIMEOUT_MS": "400000"
  }
}

Proxyvariabelen

Als uitgaand verkeer vanuit uw netwerk via een proxy moet gaan, zoals Zscaler, stel dan de volledige URL van de proxy in en de server stuurt al zijn verzoeken naar de axe-server erdoorheen, inclusief de opstart, API-sleutelcontroles en herstelopdrachten.

Kleine letters (https_proxy, http_proxy, no_proxy) werken ook en hebben voorrang als beide zijn ingesteld.

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NO_PROXY": "intranet.example.com"
  }
}

• De scanbrowser gebruikt dezelfde proxy als de serververzoeken aan de axe-server. Lijst alle intranetsites die u scant in NO_PROXY.
• npm-distributie: lokale adressen (localhost, *.localhost, 127.0.0.0/8 en [::1]) verbinden altijd direct, zodat scans van lokale ontwikkelservers niet worden beïnvloed.
• Docker-distributie: de server herschrijft localhost-URL's naar het adres van uw Docker-host (zie Scans van lokale ontwikkelservers), wat geen lokaal adres is binnen de container. Voeg dat adres toe aan NO_PROXY zodat deze scans direct verbinden. De server logt de herschreven URL elke keer dat het een localhost-pagina scant, onder Rewriting localhost URL using resolved IP of docker host.
• De scanbrowser kan geen proxy gebruiken die een gebruikersnaam en wachtwoord nodig heeft. De server logt een waarschuwing wanneer de proxy-URL referenties bevat.
• De URL moet een volledige http:// of https://-URL zijn. Als de proxy die de server voor AXE_SERVER_URL gebruikt dat niet is, stopt de server bij het opstarten met een bericht dat de variabele benoemt. Een proxyvariabele die de server niet gebruikt, zoals HTTP_PROXY met de standaard https:// axe-server, wordt genegeerd.
• Als de proxy TLS-verkeer inspecteert, stel ook NODE_EXTRA_CA_CERTS in op het pad van het CA-certificaat van de proxy.

Voor de Docker-distributie, geef deze door in de container met -e, op dezelfde manier als AXE_API_KEY.

Proxies met OAuth 2.0

Als u OAuth 2.0 gebruikt, heeft de @deque/axe-auth CLI die u inlogt en uw tokens vernieuwt ook de proxy nodig. Stel NODE_USE_ENV_PROXY=1 naast HTTPS_PROXY in zodat Node.js zijn verzoeken via de proxy verstuurt. Dit vereist Node.js 22.21 of later.

Wanneer u de server start via axe-auth run, voeg deze dan toe aan hetzelfde env-blok:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NODE_USE_ENV_PROXY": "1"
  }
}

Wanneer u axe-auth login zelf uitvoert, stel beide variabelen eerst in dezelfde terminal in.

NODE_EXTRA_CA_CERTS

Stel NODE_EXTRA_CA_CERTS in op het pad van een PEM-bestand met het CA-certificaat van uw organisatie wanneer uw netwerk een interne CA of een proxy gebruikt die TLS-verkeer inspecteert. De server leest dit op elk platform, zodat zijn eigen verzoeken aan de axe-server het CA vertrouwen zodra het bestand wordt geparseerd.

Of de scanbrowser ook de CA vertrouwt, hangt af van uw platform:

• Docker — werkt automatisch. Monteer het certificaat in de container en wijs de variabele erop:

  {
    "mcpServers": {
      "axe-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "AXE_API_KEY",
          "-e",
          "NODE_EXTRA_CA_CERTS=/certs/ca.pem",
          "-v",
          "/path/to/your/ca.pem:/certs/ca.pem:ro",
          "dequesystems/axe-mcp-server"
        ],
        "env": {
          "AXE_API_KEY": "<your-api-key>"
        }
      }
    }
  }

• npm op Linux — werkt automatisch zodra certutil is geïnstalleerd (libnss3-tools op Debian/Ubuntu, nss-tools op RHEL/Fedora). Zonder deze start de server zonder browservertrouwen en logt een waarschuwing. Het CA blijft vertrouwd door Chromium op die machine nadat de server is afgesloten.

• npm op macOS en Windows — voeg de CA zelf toe, aan uw inlogsleutelhanger (macOS) of uw Huidige Gebruiker Vertrouwde Root-opslag (Windows), alleen vertrouwd voor SSL. De server logt bij het opstarten welke opslag gebruikt moet worden.

Op Linux en Docker wordt alleen het eerste certificaat in het bestand aan de browser toegevoegd, dus wijs NODE_EXTRA_CA_CERTS naar de enkele CA waar uw sites naar ketenen.

De server leest NODE_EXTRA_CA_CERTS alleen bij het opstarten, dus start opnieuw nadat u de variabele hebt ingesteld of gewijzigd. Zie Onbetrouwbare certificaten als scans nog steeds falen.

NODE_TLS_REJECT_UNAUTHORIZED

Het instellen van NODE_TLS_REJECT_UNAUTHORIZED op "0" schakelt certificaatcontroles uit zowel op de server als in de scanbrowser. Het is een laatste redmiddel wanneer NODE_EXTRA_CA_CERTS geen optie is, zoals bij een snelle lokale test tegen een site met een zelfondertekend certificaat.

{
  "env": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Voor de Docker-distributie, geef het door in de container met -e NODE_TLS_REJECT_UNAUTHORIZED=0.

Variabelen voor gefaseerde selectie

Deze zijn van toepassing op gefaseerde selectie voor de Interactive Elements IGT. De eerste oproep pauzeert de uitvoering en houdt zijn browser open totdat uw agent de tweede oproep doet, dus deze beperken hoe lang een gepauzeerde uitvoering wacht en hoeveel browsers tegelijkertijd open kunnen blijven.

Verhoog SELECTION_SESSION_TTL_MS als u regelmatig meer dan drie minuten nodig heeft om een lange lijst met elementen te bekijken. Beide waarden moeten positieve gehele getallen zijn; de server weigert anders te starten.

{
  "env": {
    "SELECTION_SESSION_TTL_MS": "600000"
  }
}

AXE_PAGE_LOAD_DELAY_MS

In tegenstelling tot de variabelen hierboven is dit geen time-out. Het is een vaste vertraging die de server altijd wacht nadat de navigatie is voltooid, voordat het enige before acties uitvoert en voordat het start met scannen. Het bestaat voor pagina's die blijven renderen na het laden zonder iets betrouwbaars om op te wachten. Elke scan die deze server uitvoert, betaalt de vertraging volledig, dus houd het klein.

{
  "env": {
    "AXE_PAGE_LOAD_DELAY_MS": "2000"
  }
}

Geef de voorkeur aan een waitFor stap in de analyze tool's before array waar je een element kunt benoemen dat alleen bestaat als de pagina tot rust is gekomen. waitFor gaat verder op het moment dat dat element verschijnt, dus het is zowel betrouwbaarder als meestal sneller dan een algemene vertraging.

Uw AI-agent configureren (Aanbevolen)

Om ervoor te zorgen dat uw AI-codeeragent de Axe MCP Server-tools correct gebruikt en de toegankelijkheidsrichtlijnen volgt, kunt u hem voorzien van aangepaste instructies. Deze instructies helpen de agent het juiste werkproces voor het analyseren en oplossen van toegankelijkheidsproblemen te begrijpen.

Waar instructies toe te voegen

De methode verschilt per client:

• VS Code met GitHub Copilot - Voeg toe aan .github/copilot-instructions.md in de hoofdmap van uw project
• Cursor - Voeg toe aan "Cursorregels" in de instellingen
• Claude Code - Voeg toe aan een CLAUDE.md-bestand in de hoofdmap van uw project
• Claude Desktop - Voeg toe aan aangepaste instructies in de instellingen
• Andere MCP-clients - Raadpleeg de documentatie van uw klant voor configuratie van aangepaste instructies

Voorbeeldwerkstroominstructies

Hieronder staat een aanbevolen sjabloon dat u kunt aanpassen voor uw agent:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. remediate → Pass ALL violations in one batched call to get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Waarom dit belangrijk is

Deze instructies zorgen ervoor dat uw agent:

• Gebruik maakt van Deque's expertise - Maakt gebruik van AI-modellen getraind op decennia aan data over toegankelijkheidsbeoordeling in plaats van algemene LLM-kennis
• Volgt de beste praktijken - Past consistente, WCAG-conforme oplossingen toe in plaats van generieke oplossingen
• Verifieert wijzigingen - Bevestigt altijd dat de oplossingen daadwerkelijk de problemen hebben opgelost
• Vermijdt valse zekerheid - Veronderstelt niet te weten hoe toegankelijkheidsproblemen moeten worden opgelost zonder deskundige begeleiding

Hoewel optioneel, verbetert het verstrekken van deze instructies de kwaliteit en betrouwbaarheid van toegankelijkheidsoplossingen in je codebase aanzienlijk.