Resolución de problemas

Esta página cubre problemas comunes en ambas Docker y npm. Los problemas que se aplican solo a una distribución están etiquetados en consecuencia.

El servidor no se inicia

• Asegúrese de que Docker esté en funcionamiento (distribución de Docker), o de que Chromium esté instalado (distribución de npm — vea instalación de Chromium)
• Verifique que sus credenciales sean correctas: ya sea su AXE_API_KEY o su AXE_ACCESS_TOKEN, pero no ambas (el servidor falla al inicio si ambas están configuradas)
• Verifique que tenga acceso al servidor axe MCP (contacte con soporte si es necesario)

Tiempos de espera de escaneo

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

El escaneo del servidor de desarrollo local falla con ERR_CONNECTION_REFUSED

Esto se aplica a la distribución de Docker — con la distribución de npm el servidor se ejecuta directamente en su host y puede acceder a los servicios localhost normalmente.

Si la herramienta analyze falla con un error net::ERR_CONNECTION_REFUSED al intentar escanear un servidor de desarrollo que se ejecuta localmente, esto es probablemente porque axe MCP Server se ejecuta dentro de un contenedor Docker y no puede acceder a los servicios vinculados solo a localhost (es decir, 127.0.0.1) en su máquina host.

**Ejemplo de error**:

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

**Solución**: Inicie su servidor de desarrollo con la opción --host configurada en 0.0.0.0 para que escuche en todas las interfaces de red, haciéndolo accesible 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

Problemas con Docker

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

Instalación de Chromium (npm)

Esta sección se aplica a la distribución de npm. La distribución de Docker incluye su propio navegador, por lo que los usuarios de Docker no necesitan instalar Chromium y no se ven afectados por los errores descritos aquí.

Qué significa el error

El servidor axe MCP realiza escaneos de accesibilidad conduciendo un navegador real a través de Playwright. Con la distribución de npm, ese navegador — Chromium — debe estar instalado en su host. Si falta, o si la versión instalada no coincide con la revisión de Chromium que espera la versión de Playwright incluida en el servidor, el servidor no arranca (o falla en el primer escaneo) con un error que indica que no se pudo lanzar Chromium.

Esto se espera en una instalación nueva y es sencillo de arreglar.

Corrección estándar

Instale la revisión de Chromium que coincide con la versión de Playwright que el servidor axe MCP incluye — actualmente 1.60.0. Fije Playwright en esa versión para que un npx playwright simple no se resuelva en una versión más reciente con una revisión de Chromium que el servidor no soporte:

npx playwright@1.60.0 install chromium

Luego reinicie el servidor MCP (o su cliente MCP) e intente de nuevo.

Seguimiento en Linux

En Linux, Chromium también depende de una serie de bibliotecas del sistema que pueden no estar presentes. Si el navegador aún falla al iniciar después de la solución estándar, instale esas dependencias:

sudo npx playwright@1.60.0 install-deps chromium

También puede combinar ambos pasos en un solo comando:

sudo npx playwright@1.60.0 install --with-deps chromium

Use un navegador que ya tenga

Si ya tiene un binario compatible de Chrome/Chromium en su host, puede evitar por completo la instalación de Playwright configurando la variable de entorno AXE_CHROME_PATH a ese binario. Esta suele ser la solución más rápida cuando la descarga de Playwright está bloqueada (red restringida, proxy) o cuando no es posible instalar dependencias del sistema. Consulte AXE_CHROME_PATH para ver los requisitos — tenga en cuenta que Google Chrome estable 137+ no es compatible, y el valor debe ser un binario ejecutable en lugar de un paquete .app.

Por qué Chromium no está incluido

Playwright fija un revisión específica de Chromium a cada versión de Playwright, y esa revisión cambia con el tiempo. Incluir un binario del navegador en el paquete npm inflaría significativamente su tamaño, vincularía el paquete a un binario de una plataforma y quedaría obsoleto tan pronto como Playwright actualizara su revisión fija. Instalar Chromium a través de Playwright garantiza que obtenga exactamente la revisión que su versión instalada espera, para su plataforma. (La distribución de Docker puede incluir un navegador porque la imagen está construida para un entorno único y conocido.)

Re-ejecutando después de una actualización de axe-mcp-server

Actualizar axe-mcp-server puede incorporar una versión más nueva de Playwright, la cual puede fijar un revisión más reciente de Chromium diferente al que está actualmente instalado. Cuando eso suceda, es posible que vea el mismo error de inicio nuevamente después de una actualización. La solución es la misma: vuelva a ejecutar la instalación con la versión de Playwright que incluye el servidor actualizado para que Chromium coincida:

npx playwright@1.60.0 install chromium

Como regla general, vuelva a ejecutar este comando — usando la versión de Playwright que incluye la versión actual — cada vez que actualice axe-mcp-server y el servidor reporte una falta de coincidencia de Chromium al iniciarse.

Errores de autenticación

Clave de API

• Verifique que su clave de API sea válida y no haya expirado
• Asegúrese de que su suscripción al Portal de Cuentas axe incluya acceso al Servidor MCP
• Compruebe que la clave de API fue creada para el producto "axe MCP Server"
• Confirme que solo se haya configurado AXE_API_KEY — si también está configurado AXE_ACCESS_TOKEN, el servidor fallará al iniciar
• Confirme que la URL de su servidor axe sea correcta — si su organización utiliza una instancia regional, nube privada o local de axe, AXE_SERVER_URL debe estar configurado en la URL base de su instancia. Consulte Referencia de Configuración para obtener más detalles.

OAuth

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

Obteniendo ayuda

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

1. Revise la consola/descripción de errores del desarrollador de su cliente MCP para obtener mensajes de error detallados (por ejemplo, la consola de desarrollador de VS Code, las herramientas de desarrollo de Cursor, o la salida de --debug de Claude Code)
2. Revise los registros del servidor: los registros del contenedor Docker o los registros de su cliente MCP al usar la distribución de npm
3. Contacte a nuestro equipo de soporte en helpdesk@deque.com con:
   • Su cliente MCP y su versión
   • Su versión de Docker (distribución de Docker) o versión de Node.js (distribución de npm)
   • Mensajes de error completos
   • Pasos para reproducir el problema