Autenticación

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

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.

note

Configura ya sea AXE_API_KEY o AXE_ACCESS_TOKEN — no ambos. El servidor fallará al iniciarse si ambas variables están configuradas.

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

  • Node.js 22.13.0 o posterior, que @deque/axe-auth requiere (la distribución npm del servidor en sí necesita 22.19.0 o posterior)
  • 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
note

Es posible que su sistema operativo le pida que otorgue acceso al llavero la primera vez que se almacenen tokens.

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:

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 son de corta duración. Una configuración que inyecta un token con @deque/axe-auth token lo captura una vez, en el inicio del servidor, por lo que una sesión del agente que dure más que la vida útil del token comenzará a devolver errores de autenticación.

Hay dos maneras de manejar esto:

  • Recomendado: ejecute el servidor bajo @deque/axe-auth run, lo que mantiene el token actualizado para toda la sesión automáticamente.
  • De lo contrario: reinicie la conexión del servidor MCP en su cliente. La configuración vuelve a ejecutar @deque/axe-auth token en cada inicio del servidor, lo que obtiene un token nuevo.

Mantener una sesión larga activa

@deque/axe-auth run lanza y supervisa el servidor MCP de axe, renovando su token de acceso antes de que expire, por lo que una sesión que dure horas nunca alcanzará la expiración del token, sin reinicio y sin pasos manuales.

Apunte su cliente MCP a run como el comando del servidor en lugar del servidor mismo, y pase el comando de lanzamiento después de --. Gestiona la vida del proceso del servidor igual que cualquier otro servidor stdio.

Distribución npm:

{
  "command": "npx",
  "args": ["-y", "@deque/axe-auth", "run", "--", "npx", "axe-mcp-server"],
  "env": {
    "AXE_TOKEN_REFRESH_PORT": "9223"
  }
}

Distribución de Docker: publique el puerto de actualización en el loopback del host, reenvíe las variables de autenticación al contenedor y vincule el oyente a 0.0.0.0 dentro:

{
  "command": "npx",
  "args": [
    "-y",
    "@deque/axe-auth",
    "run",
    "--",
    "docker",
    "run",
    "-i",
    "--rm",
    "-p",
    "127.0.0.1:9223:9223",
    "-e",
    "AXE_ACCESS_TOKEN",
    "-e",
    "AXE_TOKEN_REFRESH_PORT",
    "-e",
    "AXE_TOKEN_REFRESH_SECRET",
    "-e",
    "AXE_TOKEN_REFRESH_HOST=0.0.0.0",
    "dequesystems/axe-mcp-server:latest"
  ],
  "env": {
    "AXE_TOKEN_REFRESH_PORT": "9223"
  }
}
important

AXE_TOKEN_REFRESH_HOST=0.0.0.0 es requerido bajo Docker. Un puerto publicado se reenvía a la interfaz de red del contenedor, no a su loopback, por lo que la vinculación por defecto al loopback sería inalcanzable. Publicar como 127.0.0.1:9223:9223 mantiene el endpoint fuera de las interfaces externas de su host, y el secreto compartido, no el aislamiento del contenedor, es lo que protege el endpoint en sí.

note

Su token de actualización nunca sale de su máquina. Solo los tokens de acceso de corta duración se envían al servidor, a través de una conexión loopback autenticada por un secreto compartido que run genera para la sesión. Esta es la misma propiedad de aislamiento que mantiene el token de actualización fuera del contenedor.

Vea Variables de actualización de token para las variables de entorno del servidor involucradas.

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]
Bandera Descripción
--server <url> URL base de tu instancia de axe. Por defecto es https://axe.deque.com. Solo es necesario para nubes privadas, regiones fuera de EE.UU. o instalaciones locales.
--force Omitir la confirmación de reautenticación cuando ya haya iniciado sesión.
--allow-insecure-issuer Permitir URLs http no-loopback (el defecto es solo https; el loopback http siempre está permitido). Se aplica solo a login; token y logout usan la política persistida en el inicio de sesión.
--no-allow-insecure-issuer Forzar allowInsecureIssuer=false para el nuevo login (y la entrada que persiste). Mutuamente excluyente con --allow-insecure-issuer. token y logout ignoran esta bandera.

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

run

Lanza y supervisa el servidor MCP de axe, manteniendo su token de acceso actualizado durante la vida de la sesión. Configúrelo como el comando del servidor del cliente MCP en lugar de invocarlo manualmente. Vea Mantener una sesión larga activa.

npx @deque/axe-auth run [options] -- <server launch command>
Bandera Descripción
--port <port> Puerto loopback utilizado para enviar tokens actualizados al servidor. Equivalente a AXE_TOKEN_REFRESH_PORT. Opcional bajo npm: sin uno, run elige un puerto libre para la sesión. Requerido cuando el comando envuelto es un entorno de contenedor (docker, podman, o nerdctl), que solo puede alcanzar un puerto que usted publique: run rechaza aquellos sin un puerto fijado.
--secret <secret> Secreto compartido que autentica cada envío. Equivalente a AXE_TOKEN_REFRESH_SECRET. Generado automáticamente a menos que fije un valor.

Funciona con ambas distribuciones, la de npm y la de Docker, en macOS, Windows y Linux.

--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

Plataforma Almacenamiento de Tokens
macOS Llavero de macOS
Windows Administrador de Credenciales de Windows
Linux Servicio Secreto D-Bus (GNOME Keyring, KWallet, etc.)
caution

Linux: @deque/axe-auth requiere un servicio secreto de D-Bus funcionando. Entornos sin cabeza o de escritorio minimalista pueden no tener uno disponible. Si ves un error como:

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

pide a tu administrador del sistema que configure GNOME Keyring o un proveedor de Servicio Secreto compatible.

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

Ejecute el servidor bajo @deque/axe-auth run, que renueva el token por usted y elimina el problema por completo. Sin él, reinicie la conexión del servidor MCP en su cliente para obtener un token nuevo. Vea Duración de token arriba.

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.

Is this page helpful?

Help us improve this page

Still need help?