Referencia de Configuración

Esta página documenta las variables de entorno que lee el servidor Axe MCP y las instrucciones personalizadas recomendadas para tu agente de IA. Estas se aplican a ambos Docker y npm. Para saber dónde colocar estos valores, consulta tu guía de configuración del cliente.

Opciones de Configuración

El servidor Axe MCP admite varias variables de entorno para la personalización:

AXE_SERVER_URL

El valor predeterminado (https://axe.deque.com) es correcto para la mayoría de los usuarios: aquellos en la instancia SaaS compartida de Deque en EE. UU. Si tu organización usa alguno de los siguientes, debes configurar AXE_SERVER_URL a la URL base de tu instancia:

• Un instancia de SaaS regional (UE, Australia, Fráncfort, etc.)
• Un cloud privado despliegue
• Una on-premises instalación

Si no estás seguro de qué instancia utiliza tu organización, verifica la URL que usas para iniciar sesión en el Portal de Cuentas Axe o pregunta a tu administrador.

Configura AXE_SERVER_URL explícitamente en el bloque env de la configuración de tu servidor MCP. Los guías de configuración del cliente incluyen ejemplos que muestran exactamente dónde añadirlo.

AXE_CHROME_PATH

Solo distribución npm. Esto no es compatible con Docker, que siempre usa su navegador integrado — el servidor no se inicia si AXE_CHROME_PATH se configura en la distribución de Docker.

Por defecto, la distribución de npm usa la versión de Chromium que instalas a través de Playwright. Configura AXE_CHROME_PATH con la ruta completa de un binario existente de Chrome/Chromium para usar ese en su lugar y omitir la instalación de Playwright.

• El valor debe ser un archivo binario ejecutable, no un paquete o directorio .app. En macOS, por ejemplo, apunta al binario dentro del paquete: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• El binario debe iniciarse y responder a --version. El servidor valida esto al iniciar y falla rápidamente con Unable to find specified chrome instance si no puede.
• Google Chrome de marca estable 137 y posteriores no es compatible. Usa Chrome para pruebas u otro binario compatible con Chromium.

Las herramientas analyze y igt también aceptan un argumento chromePath por llamada, que tiene prioridad sobre AXE_CHROME_PATH para esa llamada.

AXE_ADVANCED_RULES

Establece el preajuste de confianza Reglas avanzadas para cada escaneo que este servidor ejecute, anulando la configuración predeterminada de Axe de tu organización, siempre que tu administrador permita a los usuarios cambiar la configuración.

Los valores aceptados son "precise" (o "90%"), "balanced" (o "70%"), "thorough" (o "50%") y "disabled". Los valores no distinguen entre mayúsculas y minúsculas.

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

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

La herramienta analyze también acepta un argumento advancedRules por llamada, que tiene prioridad sobre AXE_ADVANCED_RULES para esa llamada. Si su administrador ha bloqueado la configuración, ambos se ignoran en favor del preestablecido de la organización. Ver Reglas avanzadas para conocer las reglas de precedencia completas y el bloque de respuesta advancedRules.

AXE_SCREENSHOT_DIR

Establece el directorio en el que la herramienta analyze guarda capturas de pantalla cuando una llamada pasa screenshot.save sin un camino explícito. No tiene efecto en las llamadas que establecen screenshot.saveTo, que siempre prevalece, ni en las llamadas que no guardan en absoluto.

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

Las rutas relativas se resuelven en relación con el directorio de trabajo del servidor. El valor predeterminado es el directorio temporal de su sistema operativo.

Variables de actualización de token

Esto se aplica solo a OAuth 2.0, y permite que un servidor en ejecución acepte un token de acceso recién renovado para que una sesión que supera su token no necesite reinicio. El escucha está desactivado por defecto y solo comienza cuando se configuran AXE_TOKEN_REFRESH_PORT y AXE_TOKEN_REFRESH_SECRET.

Normalmente no configura estos de manera manual. @deque/axe-auth run supervisa el servidor y los proporciona por usted: usted elige un puerto, y él genera el secreto.

Su token de actualización nunca se envía al servidor; solo los tokens de acceso de corta duración lo hacen, y el secreto compartido es lo que protege el punto final. Ver Mantener viva una sesión larga para configuraciones completas de Docker y npm.

IGT_TIMEOUT_MS

Delimita una ejecución de Prueba Guiada Inteligente, medida desde el momento en que comienza la prueba hasta que se reciben sus resultados. Se aplica tanto a las llamadas de analyze que pasan igtTools como al obsoleto Herramienta igt.

Una prueba está potenciada por IA y trabaja a través de los elementos interactivos de la página uno a la vez, por lo que legítimamente se ejecuta mucho más tiempo que un escaneo. Su valor predeterminado está dimensionado para eso, por lo que es mucho mayor que BROWSER_TIMEOUT_MS. Una ejecución que excede su límite falla con un error que nombra el presupuesto que sobrepasó:

IGT timed out after 200000ms

Aumente IGT_TIMEOUT_MS cuando una página tenga suficientes elementos interactivos para necesitar tiempo extra. Aumentar BROWSER_TIMEOUT_MS no ayudará: cada tiempo de espera en esta página es su propio presupuesto independiente, y el escaneo ya había terminado antes de que comenzara la prueba.

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

Variables de selección por fases

Estas se aplican a selección por fases para el IGT de Elementos Interactivos. La primera llamada pausa la ejecución y mantiene su navegador abierto hasta que tu agente realiza la segunda llamada, de modo que estos limitan cuánto tiempo espera una ejecución pausada y cuántos navegadores pueden mantenerse abiertos a la vez.

Aumenta SELECTION_SESSION_TTL_MS si habitualmente necesitas más de tres minutos para revisar una larga lista de elementos. Ambos valores deben ser enteros positivos; de lo contrario, el servidor se negará a iniciar.

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

AXE_PAGE_LOAD_DELAY_MS

A diferencia de las variables anteriores, esto no es un tiempo de espera. Es un retraso fijo que el servidor siempre espera después de que la navegación se completa, antes de ejecutar cualquier Acciones before y antes de escanear. Existe para páginas que continúan renderizándose después de la carga sin nada fiable que esperar. Cada escaneo que este servidor realiza paga el retraso en su totalidad, así que mantenlo pequeño.

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

Prefiera un Paso waitFor en el array de before del herramienta analyze donde pueda nombrar un elemento que solo existe una vez que la página se ha estabilizado. waitFor continúa en el momento en que aparece ese elemento, por lo que es tanto más fiable como generalmente más rápido que un retraso generalizado.

Configuración de su agente de IA (Recomendado)

Para asegurarte de que tu agente de codificación de IA utilice correctamente las herramientas del servidor Axe MCP y siga las mejores prácticas de accesibilidad, puedes proporcionarle instrucciones personalizadas. Estas instrucciones ayudan al agente a comprender el flujo de trabajo adecuado para analizar y remediar problemas de accesibilidad.

Dónde agregar las instrucciones

El método varía según el cliente:

• VS Code con GitHub Copilot - Añadir a .github/copilot-instructions.md en la raíz de tu proyecto
• Cursor - Añadir a "Reglas de Cursor" en configuración
• Claude Code - Añadir a un archivo CLAUDE.md en la raíz de tu proyecto
• Claude Desktop - Añadir a instrucciones personalizadas en configuración
• Otros clientes MCP - Consulta la documentación de tu cliente para la configuración de instrucciones personalizadas

Ejemplo de instrucciones de flujo de trabajo

A continuación se presenta una plantilla recomendada que puede adaptar para su agente:

# 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

Por qué es importante

Estas instrucciones aseguran que su agente:

• Usa la experiencia de Deque - Aprovecha modelos de IA entrenados en décadas de datos de evaluación de accesibilidad en lugar de conocimiento general de LLM
• Sigue las mejores prácticas - Aplica arreglos consistentes, compatibles con WCAG, en lugar de soluciones genéricas
• Verifica los cambios - Siempre confirma que los arreglos realmente resolvieron los problemas
• Evita la falsa confianza - No asume que sabe cómo solucionar problemas de accesibilidad sin la orientación de expertos

Aunque es opcional, proporcionar estas instrucciones mejora significativamente la calidad y fiabilidad de las correcciones de accesibilidad en tu código.