**axe MCP Server**

Overzicht

De axe MCP Server is een Model Context Protocol (MCP) server die toegankelijkheidstests van ondernemingskwaliteit rechtstreeks in uw ontwikkelworkflow integreert. Gebouwd op het vertrouwde axe-platform stelt het ontwikkelaars in staat om uitgebreide toegankelijkheidsscans uit te voeren en deskundige richtlijnen voor correcties te ontvangen zonder hun IDE te verlaten.

De server biedt twee primaire mogelijkheden - analyze en remediate.

Beide tools integreren naadloos met MCP-compatibele clients (zoals Claude Desktop, VS Code met Copilot of Cursor) en respecteren de axe-configuratie-instellingen van uw organisatie.

Toegang Krijgen

Axe MCP Server is inbegrepen in het Axe DevTools for Web pakket.

Tools & Mogelijkheden

De analyze Tool

De analyze tool voert uitgebreide toegankelijkheidsanalyses uit op webpagina's door een scan uit te voeren via de axe DevTools Browser Extension in een echte browseromgeving. Het werkt naadloos met zowel lokale ontwikkelings-URL's (bijv. localhost:3000) als externe productie-URL's.

Wat Het Doet

1. Authenticatie - Valideert de gebruikersgegevens (ofwel een API-sleutel of een OAuth 2.0-toegangstoken) om geautoriseerde toegang te garanderen
2. Configuratie Ophalen - Haalt de organisatiespecifieke axe-configuratie instellingen van de gebruiker op, inclusief:
   • Toegankelijkheidsteststandaard (bijv. WCAG 2.2 AA)
   • axe-core versie
   • Behoeft beoordeling / best practices
3. Browsergebaseerde Analyse - Start een browserinstant in de achtergrond met de axe DevTools-extensie gemonteerd
4. Paginanavigatie - Navigeert naar de URL die door de gebruiker in hun prompt aan de AI-agent is opgegeven
5. Toegankelijkheidsscan - Voert een volledige toegankelijkheidsanalyse uit op de gerenderde pagina met behulp van de axe DevTools Browser Extension, waardoor ervoor wordt gezorgd dat de daadwerkelijke gebruikerservaring wordt getest (niet alleen de statische HTML)
6. Resultaatlevering - Geeft uitgebreide analyseresultaten terug aan de agent in een gestructureerd formaat

**Responsieve Testen**

De analyze tool ondersteunt optionele viewportWidth en viewportHeight parameters, zodat u pagina's op specifieke weergaveafmetingen kunt testen. Dit is handig voor het opsporen van toegankelijkheidsproblemen die alleen bij bepaalde schermformaten verschijnen, zoals breekpunten voor mobiel of tablet.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Wanneer deze parameters worden weggelaten, gebruikt de browser zijn standaard weergaveafmeting.

Browserinteracties voor scannen

De analyze tool ondersteunt een optionele before reeks van interactiestappen die worden uitgevoerd nadat de pagina wordt geladen maar voor de toegankelijkheidsscan. Dit opent verschillende real-world testscenario's:

• Pagina's met inlogbeveiliging — vul inloggegevens in en dien ze in voordat de pagina na inloggen wordt gescand
• Cookie-/toestemmingsbanners — verwijder banners die anders de inhoud van de pagina zouden bedekken of verbergen
• Dynamische inhoud — wacht tot de door de client gegenereerde inhoud (routewijzigingen, laat geïnjecteerde DOM) verschijnt voordat er wordt gescand

Stappen worden uitgevoerd in array-volgorde, in dezelfde browsercontext als de scan, zodat cookies, localStorage, en eventuele routewijzigingen die worden geactiveerd door click of fill blijven bestaan tijdens de scan.

De before reeks ondersteunt maximaal 20 stappen. Elke stap heeft een eigen time-out van BROWSER_TIMEOUT_MS (standaard 30000 ms); er is geen mogelijkheid om per stap aan te passen.

Ondersteunde acties

Voorbeeld: Inloggen vóór het scannen

Geef je AI-agent een instructie in natuurlijke taal — de agent vertaalt je intentie in de tooloproep:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

De agent lost de vraag op en roept de analyze tool aan met een payload die vergelijkbaar is met:

{
  "url": "http://localhost:3000",
  "before": [
    { "action": "fill", "selector": "#username", "value": "<resolved-from-.env.local>" },
    { "action": "fill", "selector": "#password", "value": "<resolved-from-.env.local>" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Belangrijke Voordelen

• Testen in Echte Browser - Test de daadwerkelijk weergegeven pagina, niet alleen de broncode, waardoor nauwkeurige resultaten worden gegarandeerd
• Organisatiestandaarden - Respecteert de axe-configuratie-instellingen van uw team voor consistente tests bij alle gebruikers
• Uitgebreide Dekking - Benut het toonaangevende axe Platform in de industrie
• **Responsieve Testen** - Test op specifieke weergavebreedtes om toegankelijkheidsproblemen bij breekpunten te detecteren
• Geauthenticeerde & Interactieve Pagina's - Scan pagina's achter een login, verwijder cookiebanners of wacht op dynamische inhoud met behulp van before acties

Uitvoer

De tool geeft een gestructureerd JSON-antwoord dat het volgende bevat:

• Alle gevonden toegankelijkheidsovertredingen
• Overtredingsniveaus (kritiek, ernstig, matig, minder)
• Specifieke elementselectors en broncode
• Regel-ID's en beschrijvingen

De remediate Tool

De remediate tool neemt elk toegankelijkheidsprobleem dat door axe wordt geïdentificeerd en genereert contextbewuste, door AI aangestuurde hersteladviezen die codeagenten kunnen vertalen naar daadwerkelijke codeoplossingen.

Wat Het Doet

1. Authenticatie - Valideert de gebruikersgegevens—ofwel een API-sleutel of een OAuth 2.0-toegangstoken (zie Authenticatie instellen)—om geautoriseerde toegang te garanderen
2. AI-krediet Gebruik - Elke remediate oproep verbruikt AI-kredieten van de toewijzing van uw organisatie, waardoor het gebruik van geavanceerde AI-modellen mogelijk wordt gemaakt die zijn getraind op de uitgebreide toegankelijkheidsexpertise van Deque
3. **AI-Gegenereerd Herstel** - Creëert een hoogwaardige, bruikbare toegankelijkheidsoplossing die codeagenten kunnen interpreteren en implementeren in de broncode

Uitvoer

De tool levert gestructureerde hersteladviezen die het volgende omvatten:

• Samenvatting op hoog niveau van de vereiste oplossing
• Specifieke codewijzigingen die nodig zijn (in HTML-formaat)
• Toegankelijkheidsredenering en WCAG-criteria
• Extra context om een juiste implementatie te garanderen

Kredietgebruik

De remediate tool maakt deel uit van het AI-Kredietbeheersysteem. Elke herstelverzoek verbruikt kredieten van de maandelijkse toewijzing van uw organisatie. Beheerders kunnen het kredietgebruik controleren via het axe Account Portal.

Installatie en Setup

Vereisten

• Docker geïnstalleerd en werkend op uw systeem
• AI-agent geconfigureerd voor axe MCP Server (zie Configuratie hieronder voor IDE-specifieke installatie-instructies)
• Een abonnement dat toegang tot axe MCP Server mogelijk maakt door te overleggen met een verkoopvertegenwoordiger van Deque

Stap 1: Authenticatie instellen

De axe MCP Server ondersteunt twee authenticatiemethoden.

Optie A: API-sleutel

1. Log in op het axe Account Portal
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 in voor uw API-sleutel
6. Klik op **Opslaan**
7. Kopieer de gegenereerde API-sleutel voor gebruik in de volgende stap

Optie B: OAuth 2.0

Optie B is OAuth 2.0-authenticatie via de @deque/axe-auth CLI. Zie OAuth 2.0-authenticatie voor installatie-instructies.

Stap 2: Haal de Docker-image op

Aanvankelijk en elke keer wanneer er een bijgewerkte versie wordt uitgebracht die u wilt gebruiken, moet u docker pull de axe MCP Server-image ophalen:

docker pull dequesystems/axe-mcp-server:latest

Stap 3: Configuratie

Kies uw IDE voor specifieke installatie-instructies:

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

Voorbeeldprompten

Zorgen dat verwachte tools worden aangeroepen

In veel IDE's zorgt het gebruik van de volgende syntaxis ("#"-voorvoegsel) ervoor dat de axe MCP Server-tools worden aangeroepen zoals verwacht:

#analyze the http://localhost:3033/ web page for accessibility issues and #remediate any violations found

Analyse van een localhost-URL voor toegankelijkheidsproblemen:

Analyze http://localhost:3000 for accessibility issues

Analyse met remediëring:

Analyze https://example.com for accessibility issues and fix any issues found

Analyseer een pagina achter een login:

Analyze http://localhost:3000 for accessibility issues. Before running the
analysis, fill in the #username and #password fields with USERNAME and
PASSWORD from ./.env.local, click the button[type=submit] button, and
wait for #main-content to appear.

Verwijder een cookiebanner voordat je scant:

Analyze https://example.com for accessibility issues, but first click the
#cookie-dismiss button to dismiss the cookie consent banner.

Uw AI Agent configureren (Aanbevolen)

Om ervoor te zorgen dat uw AI-coderingsagent de axe MCP Server-tools correct gebruikt en de beste toegankelijkheidspraktijken volgt, kunt u hem voorzien van aangepaste instructies. Deze instructies helpen de agent om de juiste workflow te begrijpen voor het analyseren en remediëren van toegankelijkheidsproblemen.

Waar instructies te plaatsen

De methode varieert per cliënt:

• **VS Code met GitHub Copilot** - Voeg toe aan .github/copilot-instructions.md in de hoofdmap van uw project
• Cursor - Voeg toe aan "Cursor Rules" 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-klanten** - Raadpleeg de documentatie van uw cliënt voor de configuratie van aangepaste instructies

Voorbeeld werkstroominstructies

Hieronder vindt u een aanbevolen sjabloon die 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:

- First use `remediate` tool for EACH violation found
- Provide the exact HTML element, rule ID, and issue description
- 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. For each violation: remediate → 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:

• **Gebruikt de expertise van Deque** - Maakt gebruik van AI-modellen die getraind zijn op decennia aan toegankelijkheidsgegevens in plaats van algemene LLM-kennis
• **Volgt beste praktijken** - Past consistente, WCAG-conforme oplossingen toe in plaats van generieke oplossingen
• **Verifieert wijzigingen** - Bevestigt altijd dat oplossingen de problemen daadwerkelijk hebben opgelost
• **Vermijdt valse zekerheid** - Neemt niet zonder meer aan dat het weet hoe toegankelijkheidsproblemen moeten worden opgelost zonder deskundige begeleiding

Hoewel optioneel, verbeteren deze instructies de kwaliteit en betrouwbaarheid van toegankelijkheidsoplossingen in uw codebase aanzienlijk.

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 die op de gedeelde Amerikaanse Deque SaaS-instantie zitten. 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 privécloud- implementatie
• Een on-premises installatie

Als u niet weet welke instantie uw organisatie gebruikt, controleer dan de URL die u gebruikt om in te loggen op het axe-accountportaal, of vraag het aan uw beheerder.

Stel AXE_SERVER_URL expliciet in het env blok van uw MCP-serverconfiguratie. De IDE-specifieke installatiehandleidingen voor VS Code met Copilot en Cursor bevatten voorbeelden die precies laten zien waar het moet worden toegevoegd.

Probleemoplossing

Veelvoorkomende problemen

Server start niet op:

• Zorg ervoor dat Docker draait
• Controleer of uw gegevens juist zijn: ofwel uw AXE_API_KEY of uw AXE_ACCESS_TOKEN, maar niet beide (de server faalt bij opstarten als beide zijn ingesteld)
• Controleer of u toegang heeft tot de axe MCP-server (neem contact op met support indien nodig)

Scan-timelimits:

• Verhoog BROWSER_TIMEOUT_MS voor complexe pagina's
• Controleer of de doel-URL toegankelijk is vanuit uw netwerk
• Controleer op netwerkconnectiviteitsproblemen

ERR_CONNECTION_REFUSED bij het analyseren van een lokale ontwikkelserver

Als de analyze tool faalt met een net::ERR_CONNECTION_REFUSED fout bij het proberen scannen van een lokaal draaiende ontwikkelserver, dit komt waarschijnlijk omdat axe MCP Server binnen een Docker-container draait en geen toegang heeft tot diensten die alleen gebonden zijn aan localhost (d.w.z. 127.0.0.1) op uw hostmachine.

Foutenvoorbeeld:

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Oplossing: Start uw ontwikkelserver met de --host vlag ingesteld op 0.0.0.0 zodat hij op alle netwerkinterfaces luistert en bereikbaar is vanuit de Docker-container:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Authenticatiefouten

API-sleutel

• Controleer of uw API-sleutel geldig is en niet verlopen
• Zorg ervoor dat uw abonnement op het axe Account Portal toegang tot MCP Server omvat
• Controleer dat de API-sleutel is aangemaakt voor het product „axe MCP Server“
• Bevestig dat alleen AXE_API_KEY is ingesteld — als AXE_ACCESS_TOKEN ook is ingesteld, zal de server niet opstarten
• Bevestig dat uw axe-server-URL correct is — als uw organisatie een regionaal, privé-cloud of on-premises axe-instantie gebruikt, AXE_SERVER_URL moet worden ingesteld op de basis-URL van uw instantie. Zie Configuratieopties voor details.

OAuth

• Bevestig dat alleen AXE_ACCESS_TOKEN is ingesteld — als AXE_API_KEY ook is ingesteld, zal de server niet opstarten
• Voer npx @deque/axe-auth token uit in uw terminal om te bevestigen dat u een geldig token heeft; als het met een andere code dan nul afsluit, authenticeer opnieuw met npx @deque/axe-auth login
• Bevestig dat uw axe-server-URL correct is
• Als uw token midden in een sessie is verlopen, herstart dan de MCP-serververbinding in uw IDE (bijv. door Claude Code opnieuw op te starten, de server aan en uit te schakelen in de MCP-instellingen van Cursor, of direct op de "Herstart"-knop van CodeLens boven de axe MCP Server-entry in mcp.json) te klikken om een nieuw token te verkrijgen
• Zie OAuth 2.0-authenticatie voor volledige probleemoplossingsstappen

Docker-gerelateerde problemen:

• Zorg ervoor dat de Docker-daemon draait
• Controleer Docker-rechten
• Controleer netwerkconnectiviteit voor het downloaden van Docker-images
• Zorg ervoor dat Docker voldoende geheugen heeft door een docker system prune

Hulp krijgen

Als u problemen tegenkomt die niet in dit probleemoplossingsgedeelte worden behandeld:

1. Controleer de VS Code-ontwikkelaarsconsole voor gedetailleerde foutmeldingen
2. Bekijk de Docker-containerlogboeken voor extra debug-informatie
3. Neem contact op met ons ondersteuningsteam op helpdesk@deque.com met:
   • Uw VS Code-versie
   • Docker-versie
   • Volledige foutmeldingen
   • Stappen om het probleem te reproduceren

Ondersteuning

Voor vragen, problemen of feedback met betrekking tot de axe MCP Server:

• Technische ondersteuning: helpdesk@deque.com
• Algemene vragen: helpdesk@deque.com
• Verkoopvragen: sales@deque.com

Veiligheid & privacy FAQ

Slaat de axe MCP Server onze broncode op?

Nee. De axe MCP Server slaat uw broncode niet op in enige database of permanente opslag.

Wanneer de analyze tool uitvoert, bevat het antwoord de HTML-broncode van elementen met toegankelijkheidsproblemen voor context- en foutopsporingsdoeleinden. Deze gegevens:

• Worden alleen teruggestuurd in het directe API-antwoord naar uw AI-agent
• Worden nooit opgeslagen in door Deque beheerde databases
• Blijven binnen uw lokale ontwikkelomgeving
• Worden verwijderd nadat de analyse is voltooid

Hoe lang blijven MCP-testresultaten op door Deque beheerde infrastructuur?

Helemaal niet. MCP-testresultaten worden niet opgeslagen in een door Deque beheerd databank- of opslagsysteem.

De analyze tool:

• Voert volledig uit binnen de Docker-container op uw machine
• Stuurt resultaten direct naar uw AI-agent
• Stuurt geen analyseresultaten naar Deque-servers

De enige uitzondering is wanneer u de remediate tool oproept, die minimale inbreukmetadata kan bevatten (zie hieronder) om AI-aangedreven hersteladviezen te genereren.

Welke gegevens worden naar Deque-servers verzonden?

Alleen bij gebruik van de remediate tool:

De volgende gegevens worden naar Deque's AI-herstellingsendpoint gestuurd om hersteladviezen te genereren:

• Regel ID - De specifieke toegangsregel die werd overtreden
• Element HTML - De HTML-opmaak van het of de getroffen elementen
• Probleemmetadata - Omschrijving van de overtreding en hersteladvies van axe-core

Deze gegevens worden uitsluitend gebruikt om hersteladvies te genereren en worden niet langdurig opgeslagen in Deque-databases.

De analyze tool stuurt geen gegevens naar Deque-servers voorbij authenticatieverzoeken (het valideren van uw API-sleutel of OAuth 2.0-toegangstoken).

Welk toegangslevel heeft de AI-agent nodig om te functioneren?

De AI-agent (Claude, Copilot, Cursor, etc.) heeft toegang nodig tot:

1. MCP Server Communicatie - De agent moet in staat zijn om de tools van de MCP-server aan te roepen via het Model Context Protocol

2. Antwoordgegevens van tools - De agent ontvangt:

   • Gegevens over toegankelijkheidsovertredingen van analyze oproepen
   • Hersteladviezen van remediate oproepen
   • Deze gegevens zijn noodzakelijk voor de agent om problemen te begrijpen en codeherstel te genereren

3. Uw codebasis (optioneel) - Als u wilt dat de agent automatisch codeherstel toepast, heeft het toegang nodig tot uw broncodebestanden

• Dit is standaard voor AI-coderingsassistenten in IDE's (VS Code, Cursor, enz.)
• Niet vereist als u de tools alleen gebruikt voor analyse en begeleiding (bijv., via Claude Desktop-app)

De MCP-server zelf heeft toegang nodig tot:

• URL's die u opgeeft voor testen (ondersteunt zowel lokaal als op afstand)
• Uw axe-gegevens: ofwel een API-sleutel (gegenereerd in het axe-accountportaal) of een OAuth 2.0-toegangstoken (verkregen via @deque/axe-auth); verstrekt via een omgevingsvariabele

Belangrijk: De MCP-server draait lokaal in een Docker-container op uw machine. Het vereist geen uitgebreide toegang tot het bestandssysteem of verhoogde privileges buiten wat Docker vereist.

Best Practices

• Inloggegevensbeveiliging - Bewaar je AXE_API_KEY of AXE_ACCESS_TOKEN als een omgevingsvariabele, niet in de code. Met OAuth 2.0, @deque/axe-auth houdt tokens in uw OS-sleutelhanger en injecteert een nieuw toegangstoken bij het opstarten, zodat er geen langlopende geheimen in uw configuratie hoeven te blijven
• Lokale Testen - Test lokale ontwikkelings-URL's (localhost) of staging om gevoelige pre-productiecodes geïsoleerd te houden
• Netwerkisolatie - De MCP-server communiceert alleen met:
  • URL's die je expliciet aanvraagt om te analyseren
  • Deque-servers voor authenticatie (API-sleutel of OAuth 2.0-tokenvalidatie) en herstel (wanneer opgeroepen)
  • Je lokale AI-agent via het MCP-protocol
• Controleer voor Toepassing - Bekijk altijd AI-gegenereerde codewijzigingen voordat je ze in je codebase overneemt