axe MCP Server

Descripción general

El Servidor axe MCP es un servidor del Protocolo de Contexto de Modelo (MCP) que integra pruebas de accesibilidad de nivel empresarial directamente en su flujo de trabajo de desarrollo. Construido sobre la confiable plataforma axe, permite a los desarrolladores realizar escaneos de accesibilidad completos y recibir orientación experta en remediación sin salir de su IDE.

El servidor proporciona dos capacidades principales - analyze y remediate.

Ambas herramientas se integran perfectamente con clientes compatibles con MCP (como Claude Desktop, VS Code con Copilot o Cursor) y respetan las configuraciones de axe de su organización.

Obteniendo acceso

El Servidor axe MCP está incluido en el paquete Axe DevTools para Web .

Herramientas y capacidades

La analyze Herramienta

La analyze herramienta realiza un análisis de accesibilidad completo en páginas web ejecutando un escaneo a través de la extensión del navegador axe DevTools en un entorno de navegador real. Funciona perfectamente con URLs de desarrollo local (por ejemplo, localhost:3000) y URLs de producción remota.

Qué Hace

1. **Validación de Clave API** - Valida la clave API del usuario para asegurar el acceso autorizado
2. Recuperación de configuración - Obtiene la configuración de axe específica de la organización del usuario, incluyendo:
   • Estándar de pruebas de accesibilidad (por ejemplo, WCAG 2.2 AA)
   • versión de axe-core
   • Necesita revisión / mejores prácticas
3. Análisis basado en navegador - Inicia una instancia de navegador en segundo plano con la extensión axe DevTools montada
4. Navegación de la página - Navega a la URL proporcionada por el usuario en su solicitud al agente de IA
5. Escaneo de accesibilidad - Ejecuta un análisis de accesibilidad completo en la página renderizada usando la extensión del navegador axe DevTools, asegurando que se pruebe la experiencia real del usuario (no solo el HTML estático)
6. Entrega de resultados - Devuelve resultados de análisis completos al agente en un formato estructurado

Pruebas de respuesta

La analyze herramienta admite parámetros opcionales viewportWidth y viewportHeight , lo que le permite probar páginas en dimensiones específicas de visualización. Esto es útil para detectar problemas de accesibilidad que solo aparecen en ciertos tamaños de pantalla, como puntos de ruptura de móviles o tablets.

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

Cuando se omiten estos parámetros, el navegador usa su tamaño de visualización predeterminado.

Interacciones del navegador antes del escaneo

La analyze herramienta admite una matriz opcional de before pasos de interacción que se ejecutan después de que la página se carga pero antes del escaneo de accesibilidad. Esto desbloquea varios escenarios de prueba en el mundo real:

• Páginas protegidas por inicio de sesión — complete las credenciales y envíe antes de escanear la página posterior al inicio de sesión
• Banners de cookies/consentimiento — cierre los banners que de otro modo sobrepondrían o ocultarían el contenido de la página
• Contenido dinámico — espere a que aparezca contenido renderizado por el cliente (cambios de ruta, DOM inyectado tardíamente) antes de escanear

Los pasos se ejecutan en el orden del array, en el mismo contexto del navegador que el escaneo, por lo que las cookies, localStorage, y cualquier cambio de ruta desencadenado por click o fill persisten en el escaneo.

La before array admite hasta 20 pasos. Cada paso tiene su propio tiempo de espera de BROWSER_TIMEOUT_MS (por defecto 30000 ms); no hay anulación por paso.

Acciones Soportadas

Ejemplo: Iniciar sesión antes de escanear

Solicite a su agente de IA en lenguaje natural — el agente traduce su intención en la llamada a la herramienta:

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.

El agente resuelve la solicitud y llama a la analyze herramienta con una carga útil similar a:

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

Beneficios clave

• Pruebas en navegador real - Prueba la página realmente renderizada, no solo el código fuente, asegurando resultados precisos
• Estándares de la organización - Respeta las configuraciones de axe de tu equipo para pruebas consistentes en todos los usuarios
• Cobertura integral - Aprovecha la plataforma líder del sector axe
• Pruebas de respuesta - Prueba en dimensiones específicas de la ventana gráfica para detectar problemas de accesibilidad específicos de los puntos de interrupción
• **Páginas Autenticadas e Interactivas** - Escanea páginas detrás de un inicio de sesión, descarta banners de cookies o espera contenido dinámico usando before acciones

Salida

La herramienta devuelve una respuesta JSON estructurada que contiene:

• Todas las violaciones de accesibilidad encontradas
• Niveles de severidad de las violaciones (crítico, serio, moderado, menor)
• Selectores de elementos específicos y código fuente
• IDs de reglas y descripciones

La remediate Herramienta

La remediate herramienta toma cualquier problema de accesibilidad identificado por axe y genera una guía de remediación basada en IA y consciente del contexto que los agentes de codificación pueden traducir en correcciones reales de código.

Qué Hace

1. **Validación de Clave API** - Valida la clave API del usuario para asegurar el acceso autorizado
2. **Uso de Créditos de IA** - Cada remediate llamada consume créditos de IA de la asignación de su organización, habilitando el uso de modelos avanzados de IA entrenados con la extensa experiencia de accesibilidad de Deque
3. **Remediación Generada por IA** - Elabora una solución de accesibilidad de alta calidad y accionable que los agentes de codificación pueden interpretar e implementar en el código fuente

Salida

La herramienta devuelve una guía de remediación estructurada que incluye:

• Resumen de alto nivel de la solución requerida
• Cambios específicos de código necesarios (en formato HTML)
• Razonamiento de accesibilidad y criterios de WCAG
• Contexto adicional para garantizar una implementación adecuada

Uso de Créditos

La remediate herramienta es parte del Sistema de Gestión de Créditos de IA. Cada solicitud de remediación consume créditos de la asignación mensual de su organización. Los administradores pueden monitorear el uso de créditos a través del Portal de Cuentas de axe.

Instalación y Configuración

Requisitos Previos

• Docker instalado y ejecutándose en su sistema
• Agente de IA configurado para el Servidor MCP de axe (vea Configuración abajo para instrucciones de configuración específicas de IDE)
• Una suscripción que permite el acceso al Servidor MCP de axe hablando con un representante de ventas de Deque

Paso 1: Configurar la autenticación

El servidor de axe MCP soporta dos métodos de autenticación.

Opción A: Clave API

1. Inicie sesión en el Portal de Cuentas de axe
2. Navegue a la página de Claves API
3. Haz clic en **AÑADIR NUEVA CLAVE API**
4. Seleccione axe MCP Server como el producto
5. Introduce un nombre descriptivo para tu clave API
6. Haz clic en Guardar
7. Copia la clave API generada para usarla en el siguiente paso

Opción B: OAuth 2.0

La opción B es la autenticación OAuth 2.0 a través del @deque/axe-auth CLI. Vea Autenticación OAuth 2.0 para las instrucciones de configuración.

Paso 2: Descargar la imagen de Docker

Inicialmente y cada vez que se libera una versión actualizada que deseas utilizar, tendrás que docker pull la imagen del servidor axe MCP:

docker pull dequesystems/axe-mcp-server:latest

Paso 3: Configuración

Elige tu IDE para instrucciones de configuración específicas:

• Configuración en VS Code con Copilot
• Configuración en Cursor
• Configuración en Claude Code

Ejemplos de Indicaciones

Asegurando que se llamen las herramientas esperadas

En muchos entornos de desarrollo, usar la siguiente sintaxis (con el prefijo "#") garantizará que se llamen las herramientas del servidor axe MCP como se espera:

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

Analizar una URL de localhost para problemas de accesibilidad:

Analyze http://localhost:3000 for accessibility issues

Análisis con remediación:

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

Analizar una página detrás de un inicio de sesión:

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.

Cerrar una banner de cookies antes de escanear:

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

Configuración de tu Agente de IA (Recomendado)

Para asegurar que tu agente codificador de IA use correctamente las herramientas de axe MCP Server y siga las mejores prácticas de accesibilidad, puedes proporcionarle instrucciones personalizadas. Estas instrucciones ayudan al agente a entender el flujo de trabajo adecuado para analizar y remediar problemas de accesibilidad.

Dónde Agregar 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 "Cursor Rules" en los ajustes
• Claude Code - Añadir a un CLAUDE.md archivo en la raíz de tu proyecto
• Claude Desktop - Añadir a instrucciones personalizadas en los ajustes
• Otros clientes de MCP - Consulta la documentación de tu cliente para la configuración de instrucciones personalizadas

Instrucciones de Flujo de Trabajo Ejemplos

A continuación se muestra una plantilla recomendada que puedes adaptar para tu 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:

- 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

Por Qué Esto Importa

Estas instrucciones aseguran que tu agente:

• Usa la experiencia de Deque - Aprovecha los modelos de IA entrenados con décadas de datos de evaluación de accesibilidad en lugar de conocimiento general de modelos de lenguaje
• Sigue las mejores prácticas - Aplica correcciones coherentes y conformes a WCAG en lugar de soluciones genéricas
• Verifica cambios - Siempre confirma que las soluciones realmente resuelvan los problemas
• Evita confianza falsa - No asume que sabe cómo resolver problemas de accesibilidad sin orientación experta

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

Opciones de Configuración

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

AXE_SERVER_URL

El valor predeterminado (https://axe.deque.com) es correcto para la mayoría de los usuarios, aquellos que están en la instancia SaaS compartida de EE. UU. de Deque. Si su organización utiliza alguno de los siguientes, debe establecer AXE_SERVER_URL en la URL base de su instancia:

• Una instancia regional de SaaS (UE, Australia, Frankfurt, etc.)
• Una nube privada implementación
• Una instalación local instalación

Si no está seguro de qué instancia utiliza su organización, verifique la URL que utiliza para iniciar sesión en el portal de cuentas axe, o pregunte a su administrador.

Establezca AXE_SERVER_URL explícitamente en el env bloque de su configuración del servidor MCP. Las guías de configuración específicas para IDE de VS Code con Copilot y Cursor incluyen ejemplos que muestran exactamente dónde agregarlo.

Solución de Problemas

Problemas Comunes

El servidor no se inicia:

• Asegúrese de que Docker esté en funcionamiento
• Verifique que su clave API sea correcta
• Verifique que tenga acceso al servidor axe MCP (contacte con soporte si es necesario)

Tiempos de espera del escaneo:

• Aumente BROWSER_TIMEOUT_MS para páginas complejas
• Asegúrese de que la URL de destino sea accesible desde su red
• Verifique los problemas de conectividad de red

ERR_CONNECTION_REFUSED al analizar un servidor de desarrollo local

Si la herramienta analyze falla con un error net::ERR_CONNECTION_REFUSED mientras intenta escanear un servidor de desarrollo en funcionamiento localmente, es probable que esto se deba a que axe MCP Server opera dentro de un contenedor Docker y no puede acceder a servicios vinculados únicamente a localhost (es decir, 127.0.0.1) en su máquina anfitriona.

Ejemplo de error:

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

Solución: Inicie su servidor de desarrollo con la bandera --host configurada a 0.0.0.0 para que escuche en todas las interfaces de red, permitiendo el acceso desde dentro del contenedor Docker:

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

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

Errores de autenticación

Clave API

• Verifique que su clave API sea válida y no haya expirado
• Asegúrese de que su suscripción al Portal de Cuentas axe incluya acceso al MCP Server
• Confirme que la clave API se creó para el producto „axe MCP Server“
• Confirme que solo AXE_API_KEY está configurado — si AXE_ACCESS_TOKEN también está configurado, el servidor fallará al iniciar
• Confirme que la URL de su servidor de axe es correcta — si su organización utiliza una nube privada regional o en las instalaciones con una instancia axe, AXE_SERVER_URL debe estar configurado en la URL base de su instancia. Vea Opciones de Configuración para más detalles.

OAuth

• Confirme que solo AXE_ACCESS_TOKEN está configurado — si AXE_API_KEY también está configurado, el servidor fallará al iniciar
• Ejecute npx @deque/axe-auth token en su terminal para confirmar que tiene un token válido; si sale con un código diferente a cero, vuelva a autenticarse con npx @deque/axe-auth login
• Confirme que la URL de su servidor de axe es correcta
• Si su token ha expirado a mitad de sesión, reinicie la conexión del servidor MCP en su IDE (por ejemplo, reiniciando Claude Code, alternando el servidor en las configuraciones MCP de Cursor, o haciendo clic en el botón "Reiniciar" de CodeLens de VS Code directamente sobre la entrada del servidor de axe MCP en mcp.json) para obtener un nuevo token
• Vea Autenticación OAuth 2.0 para pasos completos de solución de problemas

Problemas relacionados con Docker:

• Asegúrese de que el demonio de Docker esté en funcionamiento
• Verifique los permisos de Docker
• Verifique la conectividad de la red para las descargas de imágenes Docker
• Asegúrese de que Docker tenga suficiente memoria ejecutando un docker system prune

Obteniendo ayuda

Si encuentra problemas que no están cubiertos en esta sección de solución de problemas:

1. Revise la Consola de Desarrollador de VS Code para obtener mensajes de error detallados
2. Revise los registros del contenedor de Docker para obtener información adicional de depuración
3. Contacte a nuestro equipo de soporte a helpdesk@deque.com con:
   • Su versión de VS Code
   • Versión de Docker
   • Mensajes de error completos
   • Pasos para reproducir el problema

Soporte

Para preguntas, problemas o comentarios relativos al axe MCP Server:

• Soporte técnico: helpdesk@deque.com
• Consultas generales: helpdesk@deque.com
• Preguntas de ventas: sales@deque.com

Preguntas frecuentes sobre Seguridad y Privacidad

¿El axe MCP Server captura o almacena nuestro código fuente?

No. El servidor axe MCP no captura ni almacena su código fuente en ninguna base de datos o almacenamiento persistente.

Cuando la analyze herramienta se ejecuta, la respuesta incluye el código fuente HTML de los elementos con problemas de accesibilidad para proporcionar contexto y propósitos de depuración. Sin embargo, estos datos:

• Solo se devuelven en la respuesta inmediata de la API a su agente de IA
• Nunca se almacenan en bases de datos gestionadas por Deque
• Permanecen dentro de su entorno de desarrollo local
• Se descartan después de que se complete el análisis

¿Cuánto tiempo permanecen los resultados de las pruebas MCP en la infraestructura gestionada por Deque?

No lo hacen. Los resultados de las pruebas MCP no se almacenan en ninguna base de datos o sistema de almacenamiento gestionado por Deque.

La analyze herramienta:

• Se ejecuta completamente dentro del contenedor Docker en su máquina
• Devuelve los resultados directamente a su agente de IA
• No envía los resultados del análisis a los servidores de Deque

La única excepción es cuando se llama a la remediate herramienta, que puede incluir metadatos mínimos de violación (ver más abajo) para generar orientación de corrección potenciada por IA.

¿Qué datos se envían a los servidores de Deque?

Solo al usar la remediate herramienta:

Los siguientes datos se envían al punto de acceso de remediación de IA de Deque para generar orientación de corrección:

• ID de regla - La regla de accesibilidad específica que fue violada
• HTML del elemento - El marcado HTML del(los) elemento(s) afectado(s)
• Metadatos del problema - Descripción de la violación y guía de remediación de axe-core

Estos datos se utilizan exclusivamente para generar orientación de remediación y no se almacenan a largo plazo en las bases de datos de Deque.

La analyze herramienta no envía ningún dato a los servidores de Deque más allá de las solicitudes de validación de clave API.

¿Qué nivel de acceso necesita el agente de IA para funcionar?

El agente de IA (Claude, Copilot, Cursor, etc.) necesita acceso a:

1. Comunicación del servidor MCP - El agente debe poder llamar a las herramientas del servidor MCP a través del Model Context Protocol

2. Datos de respuesta de herramientas - El agente recibe:

   • Datos de violación de accesibilidad de analyze llamadas
   • Guía de remediación de remediate llamadas
   • Estos datos son necesarios para que el agente entienda los problemas y genere correcciones de código

3. Su base de código (opcional) - Si desea que el agente aplique automáticamente correcciones de código, necesita acceso a sus archivos de código fuente

• Esto es estándar para los asistentes de codificación de IA en IDEs (VS Code, Cursor, etc.)
• No se requiere si solo está utilizando las herramientas para análisis y orientación (por ejemplo, a través de la aplicación de escritorio Claude)

El propio servidor MCP necesita acceso a:

• URLs que especifique para las pruebas (admite tanto locales como remotos)
• Su clave API de axe (generada en el Portal de Cuentas axe; proporcionada mediante variable de entorno)

Importante: El servidor MCP se ejecuta localmente en un contenedor Docker en su máquina. No requiere acceso amplio al sistema de archivos ni privilegios elevados más allá de lo que requiere Docker.

Mejores prácticas

• Seguridad de la clave API - Almacene su AXE_API_KEY como una variable de entorno, no en el código
• Pruebas locales - Pruebe las URL de desarrollo local (localhost) o de etapas para mantener aislado el código sensible previo a la producción
• Aislamiento de red - El servidor MCP solo se comunica con:
  • URLs que solicite explícitamente analizar
  • Servidores Deque para validación de clave API y corrección (cuando se solicita)
  • Su agente de IA local a través del protocolo MCP
• Revise antes de aplicar - Siempre revise los cambios de código generados por IA antes de confirmarlos en su base de código