Se connecter à Claude Code

Il s'agit de l'intégration centrale d'Almirant. En connectant votre IDE à Almirant via MCP (Model Context Protocol), l'IA peut lire vos tâches, implémenter du code, déplacer des Work Items entre les colonnes et créer des pull requests -- le tout sans quitter l'éditeur.

Qu'est-ce que MCP et pourquoi le connecter ?

MCP (Model Context Protocol) est un protocole ouvert qui permet aux outils IA, comme Claude Code ou Cursor, de communiquer avec des services externes de manière bidirectionnelle. Lorsque vous connectez Almirant via MCP :

• L'IA lit vos Work Items, boards et sprints directement
• L'IA met à jour l'état des tâches lors de l'implémentation
• L'IA crée de nouveaux Work Items lorsqu'elle détecte des sous-tâches
• L'IA accède au contexte du projet (tech stack, description, objectifs)

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Claude Code installé -- Instructions d'installation
• Un projet créé dans Almirant -- Créer votre premier projet
• Une API Key Almirant -- Nous allons la générer à l'étape suivante

Étape 1 : Générer une API Key

1. Dans Almirant, accédez à Settings depuis le menu latéral
2. Naviguez vers la section API Keys
3. Cliquez sur Créer une API Key
4. Donnez-lui un nom descriptif (par exemple « Claude Code - Ordinateur de travail »)
5. Copiez l'API Key générée

Conservez votre API Key

L'API Key ne s'affiche qu'une seule fois, à sa création. Copiez-la et conservez-la dans un endroit sûr. Si vous la perdez, vous devrez en générer une nouvelle.

Étape 2 : Obtenir le Project ID

Vous avez besoin de l'ID du projet auquel vous souhaitez connecter l'IA. Vous pouvez l'obtenir de deux façons :

Option A : depuis l'URL

Ouvrez votre projet dans Almirant et copiez l'UUID qui apparaît dans l'URL du navigateur :

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                               └──────────── voici votre projectId ────────────┘

Option B : depuis l'outil MCP

Si vous configurez la connexion sans projectId, vous pouvez utiliser l'outil list_projects pour afficher tous vos projets et leurs IDs.

Étape 3 : Configurer .mcp.json

Créez ou modifiez le fichier .mcp.json à la racine de votre dépôt :

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Remplacez les valeurs :

Placeholder	Valeur
<tu-project-id>	L'UUID du projet obtenu à l'étape 2
<tu-api-key>	L'API Key générée à l'étape 1

Exemple avec des valeurs réelles :

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}

Fichier .mcp.json dans le dépôt

Vous pouvez inclure .mcp.json dans votre dépôt afin que toute l'équipe partage la même configuration. Dans ce cas, ajoutez l'API Key comme variable d'environnement au lieu de l'inclure directement dans le fichier.

Étape 4 : Vérifier la connexion

Ouvrez Claude Code dans votre terminal et vérifiez que la connexion fonctionne :

1. Lancez Claude Code dans le répertoire du projet où vous avez créé .mcp.json
2. Demandez à Claude de lister vos projets :

> Liste mes projets Almirant

Si la connexion est correcte, Claude répondra avec la liste des projets. Si projectId est configuré, il affichera les détails du projet spécifique.

Outils MCP disponibles après la connexion :

Outil	Description
list_projects	Liste les projets disponibles
list_boards	Liste les boards du projet
list_work_items	Liste les Work Items avec filtres
create_work_item	Crée un nouveau Work Item
update_work_item	Met à jour un Work Item existant
list_sprints	Liste les sprints du projet

Configuration pour Cursor

La configuration pour Cursor est identique. La différence est l'emplacement du fichier de configuration :

Cursor utilise le même format .mcp.json. Placez le fichier à la racine de votre projet ou dans la configuration globale de Cursor selon la documentation de votre version.

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Résolution des problèmes

La connexion échoue ou ne répond pas

1. Vérifiez l'URL -- Assurez-vous que l'URL est https://api.almirant.ai/mcp (et non https://almirant.ai/mcp)
2. Vérifiez l'API Key -- Générez-en une nouvelle si vous n'êtes pas certain que l'actuelle soit correcte
3. Vérifiez le format JSON -- Une erreur de syntaxe dans .mcp.json empêchera la connexion

« Unauthorized » ou « Invalid API Key »

• L'API Key a peut-être été révoquée ou a expiré
• Accédez à Settings > API Keys dans Almirant et générez-en une nouvelle
• Mettez à jour la valeur dans votre .mcp.json

« Project not found »

• Vérifiez que le projectId dans l'URL est correct
• Vérifiez que vous avez accès au projet avec votre compte
• Essayez sans projectId et utilisez list_projects pour voir les IDs disponibles

Claude Code ne détecte pas le serveur MCP

• Assurez-vous que .mcp.json se trouve à la racine du répertoire où vous exécutez Claude Code
• Redémarrez Claude Code après avoir créé ou modifié le fichier
• Vérifiez que le JSON est valide (pas de virgules en trop, guillemets corrects)

---

Étape suivante : Votre premier flux IA -- Implémentez une tâche complète avec l'IA depuis votre IDE.