Authentification

Open Source — GitScrum MCP Server est open source sous la licence MIT. Disponible sur npm et sur GitHub. Serveur Model Context Protocol pour GitScrum — Claude, GitHub Copilot, Cursor et tout client compatible MCP disposent d'un accès opérationnel complet à votre stack de gestion de projets.

Le serveur MCP de GitScrum utilise le OAuth 2.0 Device Authorization Grant (RFC 8628) pour l'authentification. C'est le même flux utilisé par les Smart TV et les outils CLI — vous approuvez l'accès dans votre navigateur, et le serveur MCP reçoit un token sans jamais voir votre mot de passe.

Cette approche a été choisie spécifiquement pour MCP car les assistants IA ne doivent jamais gérer directement les identifiants utilisateur. L'approbation via le navigateur garantit que votre mot de passe reste entre vous et GitScrum.

Comment fonctionne l'autorisation par appareil

Le OAuth 2.0 Device Authorization Grant est conçu pour les appareils et applications qui ne peuvent pas ouvrir directement un navigateur. Dans le contexte MCP, l'« appareil » est le serveur MCP s'exécutant comme processus local, et l'approbation via le navigateur se fait sur votre machine.

Pourquoi ce flux pour MCP

Les flux OAuth traditionnels nécessitent une URI de redirection — le service redirige le navigateur vers l'application après la connexion. Les serveurs MCP communiquent via stdio (entrée/sortie standard) et n'ont pas de serveur web pour recevoir les redirections. Le Device Authorization Grant résout ce problème en découplant l'appareil de connexion (votre navigateur) de l'appareil applicatif (le serveur MCP).

Propriétés de sécurité clés :

• Votre mot de passe est uniquement saisi dans le navigateur, sur la page de connexion GitScrum
• Le serveur MCP ne voit, ne stocke et ne transmet jamais vos identifiants
• L'assistant IA reçoit uniquement un token d'accès à portée limitée
• Les permissions du token correspondent au rôle de votre compte GitScrum

Flux d'authentification

Le flux d'authentification complet implique quatre outils et deux acteurs : l'assistant IA (qui appelle les outils MCP) et vous (qui approuvez dans le navigateur).

Étape 1 : Initier la connexion

Demandez à votre assistant IA de se connecter à GitScrum. L'assistant appelle l'outil auth_login.

Vous :  "Connexion à GitScrum"
IA :    Appelle l'outil auth_login

Le serveur MCP contacte le serveur d'autorisation GitScrum et reçoit :

• Une URL de vérification où vous approuverez l'accès
• Un code utilisateur qui identifie cette demande de connexion spécifique
• Un délai d'expiration pour le code (généralement 15 minutes)

L'assistant IA vous affiche ces informations :

Ouvrez cette URL dans votre navigateur : https://gitscrum.com/device
Entrez ce code : ABCD-1234
Le code expire dans 15 minutes.

Étape 2 : Approbation dans le navigateur

Ouvrez l'URL de vérification dans n'importe quel navigateur sur n'importe quel appareil. Vous verrez une page demandant le code utilisateur.

1. Entrez le code utilisateur exactement tel qu'affiché (y compris le tiret)
2. Connectez-vous à votre compte GitScrum si vous n'êtes pas déjà connecté
3. Examinez les permissions demandées par le serveur MCP
4. Cliquez sur Approuver pour autoriser l'accès

Après l'approbation, le navigateur affiche une page de confirmation. Vous pouvez fermer l'onglet du navigateur.

Étape 3 : Compléter l'authentification

Dites à votre assistant IA que vous avez approuvé l'accès :

Vous :  "J'ai approuvé l'accès" ou "Complète la connexion GitScrum"
IA :    Appelle l'outil auth_complete

Le serveur MCP échange le code d'appareil contre un token d'accès et un token de rafraîchissement. Les deux sont stockés localement sur votre machine.

Étape 4 : Session active

L'assistant IA confirme que la session est active :

IA :   "Vous êtes authentifié en tant que john@acme.com. Vous avez accès à 3 espaces de travail."

À partir de ce moment, tous les appels d'outils MCP sont authentifiés automatiquement. Vous n'aurez pas besoin de vous reconnecter pour cette session.

Gestion des tokens

Stockage des tokens

Après une authentification réussie, les tokens sont stockés localement à :

~/.gitscrum/auth.json

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

Le fichier contient le token d'accès et le token de rafraîchissement. Il est créé avec des permissions de fichier restreintes (lisible uniquement par l'utilisateur actuel).

Rafraîchissement automatique

Les tokens d'accès expirent après une période définie. Lorsqu'un token expire, le serveur MCP utilise automatiquement le token de rafraîchissement pour obtenir un nouveau token d'accès — aucune interaction utilisateur requise.

Cela se produit de manière transparente. Vous ne verrez aucune invite d'authentification pendant l'utilisation normale. Le cycle de rafraîchissement continue jusqu'à ce que le token de rafraîchissement lui-même expire ou que vous vous déconnectiez explicitement.

Persistance de session

Votre authentification persiste entre les redémarrages du serveur MCP. Lorsque vous redémarrez votre client IA (Claude Desktop, VS Code, Cursor), le serveur MCP lit le token stocké depuis ~/.gitscrum/auth.json et reprend la session automatiquement.

Cela signifie que vous vous authentifiez une seule fois et restez connecté tant que le token de rafraîchissement est valide.

Outils d'authentification

auth_login

Initie le flux Device Authorization Grant.

Quand l'utiliser : Première configuration, ou après une déconnexion.

Ce qu'il retourne :

• verification_url — URL à ouvrir dans votre navigateur
• user_code — Code à entrer sur la page de vérification
• expires_in — Secondes avant l'expiration du code

Exemple d'interaction :

Vous :  "Connexion à GitScrum"
IA :    "Ouvrez https://gitscrum.com/device et entrez le code ABCD-1234.
         Le code expire dans 15 minutes."

auth_complete

Complète le flux d'authentification après l'approbation dans le navigateur.

Quand l'utiliser : Après avoir entré le code et approuvé l'accès dans le navigateur.

Ce qu'il retourne :

• Statut d'authentification (succès ou en attente)
• Informations utilisateur (nom, email)
• Espaces de travail accessibles

Exemple d'interaction :

Vous :  "J'ai approuvé"
IA :    "Authentifié en tant que john@acme.com. 3 espaces de travail disponibles."

Si l'approbation dans le navigateur n'a pas encore eu lieu, auth_complete retourne un statut « en attente » et l'assistant IA vous en informera.

auth_status

Vérifie l'état d'authentification actuel sans initier de connexion.

Quand l'utiliser : À tout moment pour vérifier que votre session est active.

Ce qu'il retourne :

• Si une session valide existe
• Détails de l'utilisateur authentifié
• Statut de validité du token

Exemple d'interaction :

Vous :  "Suis-je connecté à GitScrum ?"
IA :    "Oui, authentifié en tant que john@acme.com. La session est active."

auth_logout

Efface tous les tokens d'authentification stockés.

Quand l'utiliser : Lors du changement de compte, du partage d'une machine ou de la fin d'une session.

Ce qu'il fait :

• Supprime le fichier de token local (~/.gitscrum/auth.json)
• Efface tout état de token en mémoire
• Le prochain appel MCP nécessitant une authentification déclenchera un nouveau flux de connexion

Exemple d'interaction :

Vous :  "Déconnexion de GitScrum"
IA :    "Déconnecté. Tokens effacés."

Considérations de sécurité

Les identifiants n'atteignent jamais l'IA

Le Device Authorization Grant empêche spécifiquement l'assistant IA d'accéder à vos identifiants. Voici ce que chaque acteur voit :

L'assistant IA sait que l'authentification a réussi et quels espaces de travail vous sont accessibles, mais il ne manipule jamais directement les tokens. Les tokens n'existent que dans le processus du serveur MCP et dans le fichier de stockage local.

Stockage local uniquement

Les tokens sont stockés exclusivement sur votre système de fichiers local à ~/.gitscrum/auth.json. Ils ne sont jamais :

• Envoyés aux fournisseurs de modèles IA (Anthropic, OpenAI, etc.)
• Affichés dans la console ou la sortie
• Inclus dans le contexte de conversation IA
• Transmis à un tiers

Portée du token

Le token d'accès hérite des permissions de votre compte GitScrum. Si votre compte a un accès en lecture seule à certains projets, le serveur MCP a les mêmes restrictions. Le serveur MCP ne demande pas de permissions élevées au-delà de celles que votre compte possède déjà.

Limitation de débit sur l'authentification

Pour prévenir les attaques par force brute, le point de terminaison d'authentification applique une limitation de débit :

• Les tentatives multiples échouées de code d'appareil déclenchent un verrouillage automatique
• La durée du verrouillage augmente avec les échecs répétés
• Une authentification réussie réinitialise le compteur

Utilisation multi-comptes

Changer de compte

Pour passer à un autre compte GitScrum :

1. Demandez à votre assistant IA de se déconnecter : "Déconnexion de GitScrum"
2. Les tokens stockés sont effacés
3. Demandez à votre assistant IA de se connecter : "Connexion à GitScrum"
4. Complétez le flux dans le navigateur avec le nouveau compte

Machines partagées

Sur les machines partagées, déconnectez-vous toujours quand vous avez terminé. L'outil authlogout efface complètement le fichier de token local. Vérifiez avec authstatus qu'aucune session ne reste active.

Dépannage

Erreur « Code expired »

Les codes d'appareil expirent après 15 minutes. Si vous voyez cette erreur :

1. Demandez à l'assistant IA d'exécuter auth_login à nouveau
2. Un nouveau code est généré
3. Complétez le flux dans le navigateur rapidement

« Authorization pending » après l'approbation

Si auth_complete retourne « pending » même après votre approbation dans le navigateur :

• Vérifiez que vous avez entré le bon code (vérifiez les fautes de frappe)
• Assurez-vous d'avoir cliqué sur le bouton Approuver sur la page de confirmation
• Attendez quelques secondes et réessayez auth_complete — il peut y avoir un bref délai de propagation

Erreurs « Unauthorized » pendant l'utilisation

Si vous voyez des erreurs 401 pendant l'utilisation normale :

• Le token d'accès a peut-être expiré et le rafraîchissement automatique a échoué
• Exécutez authlogout suivi de authlogin pour vous ré-authentifier
• Vérifiez que votre compte GitScrum est toujours actif

Permissions du fichier de token

Si l'authentification réussit mais que les requêtes suivantes échouent, vérifiez les permissions du fichier de token :

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

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

Le fichier doit être lisible uniquement par votre compte utilisateur. Si les permissions sont trop restrictives (non lisible par vous) ou trop permissives (lisible par d'autres), ajustez en conséquence.

Le navigateur ne s'ouvre pas automatiquement

Le serveur MCP affiche l'URL pour que vous l'ouvriez manuellement. Il ne tente pas d'ouvrir votre navigateur. Copiez l'URL et collez-la dans n'importe quel navigateur.

Substitution par variable d'environnement

Pour les environnements CI/CD ou automatisés où l'approbation via le navigateur n'est pas pratique, vous pouvez contourner le flux Device Grant en définissant directement un token :

export GITSCRUM_TOKEN=your-api-token

Lorsque GITSCRUM_TOKEN est défini, le serveur MCP l'utilise directement au lieu du fichier de token stocké. Ceci est destiné aux scénarios de développement et d'automatisation — pas à l'utilisation interactive régulière.

Note de sécurité : Assurez-vous que l'environnement où GITSCRUM_TOKEN est défini est sécurisé. Les variables d'environnement peuvent être visibles par d'autres processus sur la même machine.

Étapes suivantes

• Sécurité : Modèle de sécurité complet incluant HTTPS, limitation de débit et gestion des erreurs.
• Configuration : Configuration spécifique par client et référence des variables d'environnement.
• Démarrage rapide : Guide de configuration complet si vous n'avez pas encore installé.
• Présentation du MCP : Les 29 outils et plus de 160 opérations disponibles après l'authentification.