Référence de configuration

Cette page documente les variables d'environnement que lit le serveur Axe MCP, ainsi que les instructions personnalisées recommandées pour votre agent IA. Celles-ci s'appliquent à la fois aux distributions Docker et npm. Pour savoir où placer ces valeurs, consultez votre guide de configuration client.

Options de configuration

Le serveur Axe MCP prend en charge plusieurs variables d'environnement pour la personnalisation :

AXE_SERVER_URL

La valeur par défaut (https://axe.deque.com) est correcte pour la plupart des utilisateurs — ceux sur l'instance SaaS partagée des États-Unis de Deque. Si votre organisation utilise l'un des éléments suivants, vous devez définir AXE_SERVER_URL sur l'URL de base de votre instance :

• Un instance SaaS régionale (UE, Australie, Francfort, etc.)
• Un déploiement cloud privé
• Une installation installation sur site

Si vous ne savez pas quelle instance votre organisation utilise, vérifiez l'URL que vous utilisez pour vous connecter au portail de compte Axe, ou demandez à votre administrateur.

Définissez AXE_SERVER_URL explicitement dans le bloc env de la configuration de votre serveur MCP. Les guides d'installation client incluent des exemples montrant exactement où l'ajouter.

AXE_CHROME_PATH

distribution npm uniquement. Cela n'est pas pris en charge dans Docker, qui utilise toujours son navigateur intégré — le serveur ne démarre pas si AXE_CHROME_PATH est défini sous la distribution Docker.

Par défaut, la distribution npm utilise la build de Chromium que vous installez via Playwright. Définissez AXE_CHROME_PATH sur le chemin complet d'un binaire Chrome/Chromium existant pour l'utiliser à la place et éviter l'installation de Playwright.

• La valeur doit être un fichier binaire exécutable, et non un package ou un répertoire .app. Sur macOS, par exemple, pointez vers le binaire à l'intérieur du package : /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• Le binaire doit exister et, sur macOS et Linux, se lancer et répondre à --version. Le serveur vérifie cela au démarrage et, s'il ne le peut pas, s'arrête avec un message expliquant pourquoi, comme le fait que le fichier ne soit pas exécutable ou qu'une bibliothèque système manque. Sous Windows, le serveur vérifie seulement que le fichier existe, donc un binaire qui ne peut pas se lancer échoue lorsque le premier scan commence.
• Google Chrome stable 137 et ultérieur n'est pas pris en charge. Utilisez Chrome pour les tests ou un autre binaire compatible avec Chromium.

Les outils analyze et igt acceptent également un argument chromePath par appel, qui prend le pas sur AXE_CHROME_PATH pour cet appel.

AXE_ADVANCED_RULES

Définit le préréglage de confiance Règles avancées pour chaque analyse exécutée par ce serveur, remplaçant le paramètre par défaut de la configuration Axe de votre organisation — à condition que votre administrateur autorise les utilisateurs à modifier le paramètre.

Les valeurs acceptées sont "precise" (ou "90%"), "balanced" (ou "70%"), "thorough" (ou "50%"), et "disabled". Les valeurs ne sont pas sensibles à la casse.

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

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

L'outil analyze accepte également un argument advancedRules par appel, qui prend la priorité sur AXE_ADVANCED_RULES pour cet appel. Si votre administrateur a verrouillé le paramètre, les deux sont ignorés au profit du préréglage de l'organisation. Voir Règles avancées pour les règles complètes de priorité et le bloc de réponse advancedRules.

AXE_SCREENSHOT_DIR

Définit le répertoire dans lequel l'outil analyze écrit les captures d'écran lorsqu'un appel passe screenshot.save sans chemin explicite. Cela n'a aucun effet sur les appels qui définissent screenshot.saveTo, qui l'emporte toujours, ni sur les appels qui ne sauvegardent pas du tout.

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

Les chemins relatifs sont résolus par rapport au répertoire de travail du serveur. La valeur par défaut est le répertoire temporaire de votre système d'exploitation.

Variables de rafraîchissement du jeton

Cela s'applique uniquement à OAuth 2.0, et permet à un serveur en cours d'exécution d'accepter un jeton d'accès fraîchement rafraîchi pour qu'une session qui survit à son jeton n'ait pas besoin de redémarrage. L'écouteur est désactivé par défaut et ne démarre que lorsque les deux AXE_TOKEN_REFRESH_PORT et AXE_TOKEN_REFRESH_SECRET sont définis.

Vous ne configurez pas normalement ceux-ci manuellement. @deque/axe-auth run supervise le serveur et les fournit pour vous — vous choisissez un port, et il génère le secret.

Votre jeton de rafraîchissement n'est jamais envoyé au serveur — seuls les jetons d'accès de courte durée passent, et le secret partagé est ce qui protège le point de terminaison. Voir Maintenir une longue session active pour des configurations Docker et npm complètes.

IGT_TIMEOUT_MS

Limite une exécution Test Guidé Intelligent, mesurée du moment où le test commence jusqu'au moment où ses résultats reviennent. Elle s'applique à la fois aux appels analyze qui passent par igtTools et à l'ancien igt outil.

Un test est doté d'une intelligence artificielle et fonctionne à travers les éléments interactifs de la page un à la fois, il s'exécute donc légitimement beaucoup plus longtemps qu'une analyse. Son paramètre par défaut est dimensionné pour cela, ce qui explique pourquoi il est beaucoup plus élevé que BROWSER_TIMEOUT_MS. Une exécution qui dépasse son budget échoue avec une erreur nommant le budget qu'elle a dépassé :

IGT timed out after 200000ms

L'erreur indique également la dernière étape atteinte par le test et il y a combien de temps, ce qui vous informe si le test progressait encore ou s'était arrêté :

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

Augmentez IGT_TIMEOUT_MS lorsqu'une page a suffisamment d'éléments interactifs pour nécessiter du temps supplémentaire. Augmenter BROWSER_TIMEOUT_MS n'aidera pas : chaque délai d'expiration sur cette page est son propre budget indépendant, et l'analyse était déjà terminée avant que le test ne commence.

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

Variables de proxy

Si le trafic sortant de votre réseau doit passer par un proxy, tel que Zscaler, définissez l'URL complète du proxy et le serveur enverra toutes ses requêtes au serveur axe à travers celui-ci, y compris le démarrage, la vérification des clés API et la remédiation.

Les écritures en minuscules (https_proxy, http_proxy, no_proxy) fonctionnent aussi et prennent priorité lorsque les deux sont définis.

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

• Le navigateur de scan utilise le même proxy que les requêtes du serveur vers le serveur axe. Listez tous les sites intranet que vous scannez dans NO_PROXY.
• Distribution npm : les adresses locales (localhost, *.localhost, 127.0.0.0/8, et [::1]) se connectent toujours directement, donc les scans des serveurs de développement locaux ne sont pas affectés.
• Distribution Docker : le serveur réécrit les URL localhost vers l'adresse de votre hôte Docker (voir Scans des serveurs de développement locaux), qui n'est pas une adresse locale à l'intérieur du conteneur. Ajoutez cette adresse à NO_PROXY pour que ces scans se connectent directement. Le serveur enregistre l'URL réécrite à chaque fois qu'il scanne une page localhost, sous Rewriting localhost URL using resolved IP of docker host.
• Le navigateur de scan ne peut pas utiliser un proxy nécessitant un nom d'utilisateur et un mot de passe. Le serveur enregistre un avertissement lorsque l'URL du proxy inclut des identifiants.
• L'URL doit être une URL http:// ou https:// complète. Si le proxy utilisé par le serveur pour AXE_SERVER_URL ne l'est pas, le serveur s'arrête au démarrage avec un message mentionnant la variable. Une variable de proxy que le serveur n'utilise pas, comme HTTP_PROXY avec le serveur https:// axe par défaut, est ignorée.
• Si le proxy inspecte le trafic TLS, définissez également NODE_EXTRA_CA_CERTS sur le chemin du certificat CA du proxy.

Pour la distribution Docker, passez-les dans le conteneur avec -e, de la même manière que AXE_API_KEY.

Proxies avec OAuth 2.0

Si vous utilisez OAuth 2.0, le CLI @deque/axe-auth qui vous connecte et rafraîchit vos jetons a également besoin du proxy. Définissez NODE_USE_ENV_PROXY=1 en parallèle avec HTTPS_PROXY pour que Node.js envoie ses requêtes via le proxy. Cela nécessite Node.js 22.21 ou ultérieur.

Lorsque vous lancez le serveur via axe-auth run, ajoutez-le au même bloc env :

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

Lorsque vous exécutez axe-auth login vous-même, définissez d'abord les deux variables dans le même terminal.

NODE_EXTRA_CA_CERTS

Définissez NODE_EXTRA_CA_CERTS sur le chemin d'un fichier PEM contenant le certificat CA de votre organisation lorsqu'un réseau utilise une CA interne ou un proxy qui inspecte le trafic TLS. Le serveur le lit sur chaque plateforme, donc ses propres requêtes au serveur axe font confiance à cette CA une fois le fichier analysé.

Que le navigateur de scan fasse également confiance à la CA dépend de votre plateforme :

• Docker — fonctionne automatiquement. Montez le certificat dans le conteneur et pointez la variable dessus :

  {
    "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 sur Linux — fonctionne automatiquement une fois que certutil est installé (libnss3-tools sur Debian/Ubuntu, nss-tools sur RHEL/Fedora). Sans lui, le serveur démarre sans la confiance du navigateur et enregistre un avertissement. La CA reste de confiance par Chromium sur cette machine après que le serveur s'arrête.

• npm sur macOS et Windows — ajoutez la CA vous-même, à votre trousseau de connexion (macOS) ou à votre magasin de racines de confiance de l'utilisateur actuel (Windows), uniquement de confiance pour SSL. Le serveur enregistre quel magasin utiliser au démarrage.

Sur Linux et Docker, seul le premier certificat du fichier est ajouté au navigateur, donc pointez NODE_EXTRA_CA_CERTS vers le seul CA auquel vos sites sont reliés.

Le serveur lit NODE_EXTRA_CA_CERTS uniquement au démarrage, donc redémarrez-le après avoir défini ou modifié la variable. Voir Certificats non fiables si les scans échouent toujours.

NODE_TLS_REJECT_UNAUTHORIZED

Définir NODE_TLS_REJECT_UNAUTHORIZED sur "0" désactive les vérifications des certificats à la fois dans le serveur et le navigateur de scan. C'est un dernier recours pour quand NODE_EXTRA_CA_CERTS n'est pas une option, comme un test local rapide contre un site avec un certificat auto-signé.

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

Pour la distribution Docker, passez-le dans le conteneur avec -e NODE_TLS_REJECT_UNAUTHORIZED=0.

Variables de sélection progressive

Celles-ci s'appliquent à sélection progressive pour les éléments interactifs IGT. Le premier appel met l'exécution en pause et garde son navigateur ouvert jusqu'à ce que votre agent effectue le second appel, limitant ainsi la durée d'attente d'une exécution en pause et le nombre de navigateurs pouvant être maintenus ouverts simultanément.

Augmentez SELECTION_SESSION_TTL_MS si vous avez régulièrement besoin de plus de trois minutes pour examiner une longue liste d'éléments. Les deux valeurs doivent être des entiers positifs ; sinon, le serveur refuse de démarrer.

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

AXE_PAGE_LOAD_DELAY_MS

Contrairement aux variables ci-dessus, il ne s'agit pas d'un délai d'expiration. C'est un délai fixe que le serveur attend toujours après la fin de la navigation, avant de lancer toute before actions et avant d'analyser. Il existe pour les pages qui continuent à se rendre après le chargement sans rien de fiable sur lequel s'attendre. Chaque analyse exécutée par ce serveur paie le délai en entier, alors gardez-le petit.

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

Préférez un waitFor étape dans le tableau analyze de l'outil before où vous pouvez nommer un élément qui n'existe qu'une fois que la page s'est stabilisée. waitFor continue dès que cet élément apparaît, ce qui est à la fois plus fiable et généralement plus rapide qu'un délai générique.

Configurer votre agent IA (Recommandé)

Pour garantir que votre agent de codage IA utilise correctement les outils du serveur Axe MCP et suive les meilleures pratiques en matière d'accessibilité, vous pouvez lui fournir des instructions personnalisées. Ces instructions aident l'agent à comprendre le bon flux de travail pour analyser et remédier aux problèmes d'accessibilité.

Où ajouter des instructions

La méthode varie selon le client :

• VS Code avec GitHub Copilot - Ajoutez à .github/copilot-instructions.md à la racine de votre projet
• Cursor - Ajoutez aux "Règles de curseur" dans les paramètres
• Claude Code - Ajoutez à un fichier CLAUDE.md à la racine de votre projet
• Claude Desktop - Ajoutez aux instructions personnalisées dans les paramètres
• Autres clients MCP - Consultez la documentation de votre client pour la configuration des instructions personnalisées

Exemple d'instructions de flux de travail

Ci-dessous un modèle recommandé que vous pouvez adapter pour votre 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

Pourquoi c'est important

Ces instructions garantissent que votre agent :

• Utilise l'expertise de Deque - Exploite des modèles d'IA formés sur des décennies de données d'évaluation de l'accessibilité plutôt que sur des connaissances générales de LLM
• Suit les meilleures pratiques - Applique des correctifs conformes à la WCAG de manière cohérente plutôt que des solutions génériques
• Vérifie les changements - Confirme toujours que les correctifs ont effectivement résolu les problèmes
• Évite une confiance excessive - Ne suppose pas qu'il sait comment résoudre les problèmes d'accessibilité sans guidance experte

Bien que facultatives, ces instructions améliorent significativement la qualité et la fiabilité des corrections d'accessibilité dans votre base de code.