Autenticación

Código Abierto — GitScrum MCP Server es código abierto bajo la licencia MIT. Disponible en npm y en GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor y cualquier cliente compatible con MCP tienen acceso operacional completo a tu stack de gestión de proyectos.

El GitScrum MCP Server usa OAuth 2.0 Device Authorization Grant (RFC 8628) para la autenticación. Es el mismo flujo utilizado por smart TVs y herramientas CLI — apruebas el acceso en tu navegador y el servidor MCP recibe un token sin ver nunca tu contraseña.

Este enfoque fue elegido específicamente para MCP porque los asistentes de IA nunca deberían manejar credenciales de usuario directamente. La aprobación basada en navegador asegura que tu contraseña permanezca entre tú y GitScrum.

Cómo funciona la autorización de dispositivo

El OAuth 2.0 Device Authorization Grant está diseñado para dispositivos y aplicaciones que no pueden abrir un navegador directamente. En el contexto de MCP, el "dispositivo" es el servidor MCP ejecutándose como un proceso local, y la aprobación del navegador ocurre en tu máquina.

Por qué este flujo para MCP

Los flujos OAuth tradicionales requieren una URI de redirección — el servicio redirige el navegador de vuelta a la aplicación después del login. Los servidores MCP se comunican a través de stdio (entrada/salida estándar) y no tienen un servidor web para recibir redirecciones. El Device Authorization Grant resuelve esto desacoplando el dispositivo de login (tu navegador) del dispositivo de la aplicación (el servidor MCP).

Propiedades de seguridad clave:

• Tu contraseña solo se ingresa en el navegador, en la página de login de GitScrum
• El servidor MCP nunca ve, almacena ni transmite tus credenciales
• El asistente de IA recibe solo un token de acceso con alcance limitado
• Los permisos del token coinciden con el rol de tu cuenta de GitScrum

Flujo de autenticación

El flujo completo de autenticación involucra cuatro herramientas y dos actores: el asistente de IA (que llama a las herramientas MCP) y tú (que apruebas en el navegador).

Paso 1: Iniciar login

Dile a tu asistente de IA que inicie sesión en GitScrum. El asistente llama a la herramienta auth_login.

Tú:   "Inicia sesión en GitScrum"
IA:   Llama a la herramienta auth_login

El servidor MCP contacta al servidor de autorización de GitScrum y recibe:

• Una URL de verificación donde aprobarás el acceso
• Un código de usuario que identifica esta solicitud de login específica
• Un tiempo de expiración para el código (típicamente 15 minutos)

El asistente de IA te muestra esta información:

Abre esta URL en tu navegador: https://gitscrum.com/device
Ingresa este código: ABCD-1234
El código expira en 15 minutos.

Paso 2: Aprobación en el navegador

Abre la URL de verificación en cualquier navegador de cualquier dispositivo. Verás una página solicitando el código de usuario.

1. Ingresa el código de usuario exactamente como se muestra (incluyendo el guión)
2. Inicia sesión en tu cuenta de GitScrum si aún no lo has hecho
3. Revisa los permisos solicitados por el servidor MCP
4. Haz clic en Aprobar para autorizar el acceso

Después de la aprobación, el navegador muestra una página de confirmación. Puedes cerrar la pestaña del navegador.

Paso 3: Completar autenticación

Dile a tu asistente de IA que has aprobado el acceso:

Tú:   "He aprobado el acceso" o "Completa el login de GitScrum"
IA:   Llama a la herramienta auth_complete

El servidor MCP intercambia el código de dispositivo por un token de acceso y un token de renovación. Ambos se almacenan localmente en tu máquina.

Paso 4: Sesión activa

El asistente de IA confirma que la sesión está activa:

IA:   "Estás autenticado como john@acme.com. Tienes acceso a 3 workspaces."

A partir de este momento, todas las llamadas a herramientas MCP se autentican automáticamente. No necesitarás iniciar sesión de nuevo durante esta sesión.

Gestión de tokens

Almacenamiento de tokens

Después de una autenticación exitosa, los tokens se almacenan localmente en:

~/.gitscrum/auth.json

• macOS/Linux: /Users/tunombre/.gitscrum/auth.json
• Windows: C:\Users\tunombre\.gitscrum\auth.json

El archivo contiene el token de acceso y el token de renovación. Se crea con permisos de archivo restringidos (legible solo por el usuario actual).

Renovación automática

Los tokens de acceso expiran después de un período establecido. Cuando un token expira, el servidor MCP automáticamente usa el token de renovación para obtener un nuevo token de acceso — sin intervención del usuario.

Esto sucede de forma transparente. No verás ningún aviso de autenticación durante el uso normal. El ciclo de renovación continúa hasta que el propio token de renovación expire o cierres sesión explícitamente.

Persistencia de sesión

Tu autenticación persiste entre reinicios del servidor MCP. Cuando reinicias tu cliente de IA (Claude Desktop, VS Code, Cursor), el servidor MCP lee el token almacenado de ~/.gitscrum/auth.json y reanuda la sesión automáticamente.

Esto significa que te autenticas una vez y permaneces con sesión iniciada mientras el token de renovación sea válido.

Herramientas de autenticación

auth_login

Inicia el flujo de Device Authorization Grant.

Cuándo usar: Configuración inicial, o después de cerrar sesión.

Qué devuelve:

• verification_url — URL para abrir en tu navegador
• user_code — Código para ingresar en la página de verificación
• expires_in — Segundos hasta que el código expire

Ejemplo de interacción:

Tú:   "Inicia sesión en GitScrum"
IA:   "Abre https://gitscrum.com/device e ingresa el código ABCD-1234.
       El código expira en 15 minutos."

auth_complete

Completa el flujo de autenticación después de la aprobación en el navegador.

Cuándo usar: Después de haber ingresado el código y aprobado el acceso en el navegador.

Qué devuelve:

• Estado de autenticación (éxito o pendiente)
• Información del usuario (nombre, email)
• Workspaces accesibles

Ejemplo de interacción:

Tú:   "Ya lo aprobé"
IA:   "Autenticado como john@acme.com. 3 workspaces disponibles."

Si la aprobación del navegador aún no ha ocurrido, auth_complete devuelve un estado "pendiente" y el asistente de IA te lo hará saber.

auth_status

Verifica el estado actual de autenticación sin iniciar un login.

Cuándo usar: En cualquier momento que quieras verificar que tu sesión está activa.

Qué devuelve:

• Si existe una sesión válida
• Detalles del usuario autenticado
• Estado de validez del token

Ejemplo de interacción:

Tú:   "¿Estoy conectado a GitScrum?"
IA:   "Sí, autenticado como john@acme.com. La sesión está activa."

auth_logout

Limpia todos los tokens de autenticación almacenados.

Cuándo usar: Al cambiar de cuenta, compartir una máquina o terminar una sesión.

Qué hace:

• Elimina el archivo de token local (~/.gitscrum/auth.json)
• Limpia cualquier estado de token en memoria
• La siguiente llamada MCP que requiera autenticación activará un nuevo flujo de login

Ejemplo de interacción:

Tú:   "Cierra sesión de GitScrum"
IA:   "Sesión cerrada. Tokens eliminados."

Consideraciones de seguridad

Las credenciales nunca llegan a la IA

El Device Authorization Grant previene específicamente que el asistente de IA acceda a tus credenciales. Esto es lo que cada actor ve:

El asistente de IA sabe que la autenticación fue exitosa y a qué workspaces tienes acceso, pero nunca maneja tokens directamente. Los tokens existen solo en el proceso del servidor MCP y en el archivo de almacenamiento local.

Solo almacenamiento local

Los tokens se almacenan exclusivamente en tu sistema de archivos local en ~/.gitscrum/auth.json. Nunca son:

• Enviados a proveedores de modelos de IA (Anthropic, OpenAI, etc.)
• Registrados en consola o salida
• Incluidos en el contexto de conversación de la IA
• Transmitidos a terceros

Alcance del token

El token de acceso hereda los permisos de tu cuenta de GitScrum. Si tu cuenta tiene acceso de solo lectura a ciertos proyectos, el servidor MCP tiene las mismas restricciones. El servidor MCP no solicita permisos elevados más allá de los que tu cuenta ya tiene.

Limitación de tasa en autenticación

Para prevenir ataques de fuerza bruta, el endpoint de autenticación aplica limitación de tasa:

• Múltiples intentos fallidos de código de dispositivo activan un bloqueo automático
• La duración del bloqueo aumenta con los fallos repetidos
• La autenticación exitosa restablece el contador

Uso multi-cuenta

Cambio de cuentas

Para cambiar a una cuenta de GitScrum diferente:

1. Dile a tu asistente de IA que cierre sesión: "Cierra sesión de GitScrum"
2. Los tokens almacenados se limpian
3. Dile a tu asistente de IA que inicie sesión: "Inicia sesión en GitScrum"
4. Completa el flujo del navegador con la nueva cuenta

Máquinas compartidas

En máquinas compartidas, siempre cierra sesión cuando termines. La herramienta authlogout limpia el archivo de token local completamente. Verifica con authstatus que no quede ninguna sesión activa.

Solución de problemas

Error "Code expired"

Los códigos de dispositivo expiran después de 15 minutos. Si ves este error:

1. Pide al asistente de IA que ejecute auth_login de nuevo
2. Se genera un nuevo código
3. Completa el flujo del navegador rápidamente

"Authorization pending" después de la aprobación

Si auth_complete devuelve "pending" incluso después de que aprobaste en el navegador:

• Verifica que ingresaste el código correcto (revisa errores tipográficos)
• Asegúrate de que hiciste clic en el botón Aprobar en la página de confirmación
• Espera unos segundos e intenta auth_complete de nuevo — puede haber un breve retraso de propagación

Errores "Unauthorized" durante el uso

Si ves errores 401 durante la operación normal:

• El token de acceso puede haber expirado y la renovación automática falló
• Ejecuta authlogout seguido de authlogin para re-autenticarte
• Verifica que tu cuenta de GitScrum siga activa

Permisos del archivo de token

Si la autenticación tiene éxito pero las solicitudes posteriores fallan, verifica los permisos del archivo de token:

# macOS/Linux
ls -la ~/.gitscrum/auth.json

# Windows (PowerShell)
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json"

El archivo debe ser legible solo por tu cuenta de usuario. Si los permisos son demasiado restrictivos (no legible por ti) o demasiado permisivos (legible por otros), ajústalos correspondientemente.

El navegador no se abre automáticamente

El servidor MCP muestra la URL para que la abras manualmente. No intenta abrir tu navegador. Copia la URL y pégala en cualquier navegador.

Sobrescritura mediante variable de entorno

Para entornos CI/CD o automatizados donde la aprobación basada en navegador no es práctica, puedes saltarte el flujo de Device Grant estableciendo un token directamente:

export GITSCRUM_TOKEN=tu-token-de-api

Cuando GITSCRUM_TOKEN está configurado, el servidor MCP lo usa directamente en lugar del archivo de token almacenado. Esto está destinado para escenarios de desarrollo y automatización — no para uso interactivo regular.

Nota de seguridad: Asegúrate de que el entorno donde se configura GITSCRUM_TOKEN sea seguro. Las variables de entorno pueden ser visibles para otros procesos en la misma máquina.

Próximos pasos

• Seguridad: Modelo de seguridad completo incluyendo HTTPS, limitación de tasa y manejo de errores.
• Configuración: Configuración específica por cliente para Claude Desktop, GitHub Copilot, Cursor y más.
• Inicio Rápido: Tutorial completo de configuración si aún no has instalado.
• Descripción General de MCP: Las 29 herramientas y más de 160 operaciones disponibles después de la autenticación.