Autenticación

El servidor MCP de axe admite dos métodos de autenticación. Ambos están disponibles para todos los usuarios: elija el que mejor se adapte a su flujo de trabajo:

• Clave de API: una llave de larga duración generada en el Portal de Cuentas de axe. La más sencilla de configurar.
• OAuth 2.0: inicio de sesión basado en navegador a través del CLI @deque/axe-auth, con tokens almacenados en el llavero de su sistema operativo y actualizados automáticamente.

Configura la credencial elegida en su guía de configuración del cliente. Cada página de configuración muestra las configuraciones tanto de clave API como de OAuth una al lado de la otra.

Clave de API

1. Inicia sesión en el Portal de Cuentas de axe
2. Navega al página de Claves de API
3. Haz clic en AÑADIR NUEVA CLAVE DE API
4. Selecciona Servidor MCP de axe como el producto
5. Ingrese un nombre descriptivo para su clave de API
6. Haz clic en Guardar
7. Copia la clave API generada: la pasarás al servidor como la variable de entorno AXE_API_KEY

OAuth 2.0

OAuth 2.0 utiliza el Authorization Code Flow con PKCE y almacena tokens de manera segura en el llavero de su sistema operativo, por lo que solo se autentica una vez y la CLI maneja la actualización de tokens automáticamente.

La autenticación es gestionada por @deque/axe-auth, un CLI independiente que instalas por separado en tu máquina anfitriona.

Requisitos previos

• Un versión activa de Node.js LTS
• Distribución del servidor MCP de axe que hayas elegido instalada — consulta Elegir una Distribución

Paso 1: Autenticar

Ejecute el comando de inicio de sesión:

npx @deque/axe-auth login

La CLI:

1. Abre su navegador predeterminado en la página de inicio de sesión
2. Le pedirá que inicie sesión con sus credenciales de la cuenta de axe
3. Almacena los tokens resultantes de forma segura en el llavero del sistema

Cuando todo esté listo, la terminal confirma:

✓ Authenticated.

Solo necesitas ejecutar login una vez por máquina. En invocaciones posteriores, npx @deque/axe-auth token actualiza tu token de acceso silenciosamente usando el token de actualización almacenado.

Nube privada, regiones fuera de EE.UU. o instalaciones en las instalaciones

Si tu organización utiliza una nube privada o una instancia local de axe, pasa tu URL de instancia con --server (o configura la variable de entorno AXE_SERVER_URL):

npx @deque/axe-auth login --server https://your-axe-instance.example.com

Paso 2: Configure su cliente

Usa @deque/axe-auth token en tu configuración de cliente MCP para inyectar un token de acceso válido cada vez que el servidor se inicie. Elige tu cliente para obtener instrucciones específicas de configuración:

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

Cada página de configuración incluye una sección de configuración de OAuth junto con las instrucciones de la clave API.

Gestión de sesiones

Duración de token

Los tokens de acceso OAuth tienen una corta duración. Si una sesión se prolonga más allá de la duración del token, el servidor devolverá errores de autenticación.

Solución alternativa: Reinicia la conexión del servidor MCP en tu cliente. La configuración vuelve a ejecutar @deque/axe-auth token en cada inicio del servidor, lo que obtiene un token nuevo automáticamente.

Cerrar sesión

Para revocar sus tokens en el servidor y eliminarlos del llavero del sistema:

npx @deque/axe-auth logout

Si la revocación en el servidor falla (por ejemplo, debido a un error de red), los tokens locales aún se eliminan y se imprime una advertencia.

Reautenticación

Si tu token de actualización ha expirado o ha sido revocado, @deque/axe-auth token sale con el código 1 y te indica que vuelvas a iniciar sesión. Ejecuta npx @deque/axe-auth login de nuevo. Pasa --force para omitir el mensaje de confirmación de re-autenticación:

npx @deque/axe-auth login --force

Referencia de comandos

login

Abre un navegador, completa el flujo de Autorización de Código OAuth 2.0 + PKCE, y persiste los tokens en el llavero del sistema operativo.

npx @deque/axe-auth login [options]

token

Imprime un token de acceso actualmente válido en stdout. Se actualiza silenciosamente si el token almacenado ha expirado. Sale con el código 1 si no se ha autenticado.

npx @deque/axe-auth token

logout

Revoca el token de actualización almacenado en el servidor y elimina la entrada del llavero local.

npx @deque/axe-auth logout

--help

Muestra información de ayuda para @deque/axe-auth y sus comandos.

npx @deque/axe-auth --help
npx @deque/axe-auth <command> --help

Compatibilidad con plataformas

System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).

Resolución de problemas de OAuth

El navegador no se abre automáticamente

Si login no puede abrir un navegador, imprime la URL de autorización en el terminal. Copia la URL y ábrela manualmente para completar la autenticación.

Expiración de token durante sesiones largas

Consulta Duración de token arriba. Reinicia la conexión del servidor MCP en tu cliente para obtener un token nuevo.

Error de "No autenticado" de token

Tu sesión ha expirado o los tokens fueron eliminados. Ejecuta npx @deque/axe-auth login de nuevo para re-autenticarte.

Errores de autenticación del servidor MCP

• Confirma que solo AXE_ACCESS_TOKEN está configurado (no AXE_API_KEY)
• Confirma que AXE_SERVER_URL coincide con tu URL de instancia de axe — esta debería ser la misma URL utilizada con --server durante el inicio de sesión (o https://axe.deque.com si usaste el valor por defecto)
• Ejecuta npx @deque/axe-auth token directamente en tu terminal para confirmar que tienes un token válido
• Si sale con el código 1, re-autentícate con npx @deque/axe-auth login

Llave de Linux no disponible

Consulta el aviso Compatibilidad de Plataforma arriba.