Comment connecter des agents IA à Stellary via MCP

Stellary expose un serveur Model Context Protocol (MCP) natif pour les clients IA et les boucles d'agents externes. Un client connecté peut découvrir les tools projet, lire le contexte de delivery et effectuer les actions autorisées par son identité et ses permissions.

Ce guide présente la configuration actuellement implémentée en production : transport Streamable HTTP sur https://api.stellary.co/mcp, authentification bearer et modèles d'identité distincts pour les utilisateurs et les agents de workspace.

Pour la référence runtime complète, consultez la documentation MCP de Stellary.

Ce que MCP fait — et ne fait pas

MCP standardise la communication entre une application IA et un serveur qui expose des tools, des resources ou des prompts. Il réduit le travail d'intégration propre à chaque client, mais ne garantit pas que tous les clients MCP prennent en charge le même transport, la même authentification ou les mêmes capacités.

Dans Stellary, le serveur MCP est intégré au backend. Il n'y a ni daemon séparé ni bridge à déployer. Le serveur utilise Streamable HTTP : GET sert à la découverte ou à la négociation du protocole, tandis que POST transporte les requêtes MCP.

Avant de connecter un client

Vous avez besoin :

• d'un workspace Stellary contenant au moins un projet accessible ;
• d'un client compatible avec MCP en Streamable HTTP et les headers d'autorisation personnalisés ;
• d'un personal access token pour un usage interactif, ou d'un agent token pour une boucle d'agent dédiée.

Le token n'est pas un simple secret de transport. Il détermine l'identité, l'accès aux projets, les tools disponibles et le comportement des écritures.

Étape 1 : choisir la bonne identité

Personal access token

Utilisez un personal access token (PAT) lorsque Cursor, Claude Code, Claude Desktop ou un autre client interactif doit agir en votre nom. Les tools projet et cockpit respectent toujours vos accès Stellary et les scopes accordés au token.

Créez le token depuis Paramètres > Tokens API. Commencez avec :

• projects:read pour les boards, cartes, documents et le contexte projet ;
• pilotage:read pour le cockpit et les signaux de pilotage.

Ajoutez projects:write ou pilotage:write uniquement si le client doit effectuer ces actions. Stellary prend aussi en charge notifications:read, account:read et account:write pour les surfaces REST correspondantes.

Vous pouvez également créer un PAT via l'API depuis une session utilisateur authentifiée :

curl -X POST https://app.stellary.co/api-tokens \
  -H "Authorization: Bearer VOTRE_JWT_UTILISATEUR" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cursor MCP","scopes":["projects:read","pilotage:read"]}'

Le secret en clair n'est renvoyé qu'à la création. Conservez-le dans la configuration sécurisée du client et révoquez-le s'il est exposé.

Agent token

Utilisez un agent token lorsqu'un agent de workspace dédié doit récupérer des missions en file, accéder au contexte propre aux agents ou utiliser des tools issus de plugins. Le token est lié au workspace, au périmètre projet, à la liste de tools, aux règles et au mode d'autonomie de l'agent.

Pour une boucle d'agent externe, appelez d'abord stellary_init. Ce tool renvoie les règles, skills, mode d'autonomie et tools effectivement accessibles avant le début du travail.

Le MCP_TOKEN statique et optionnel du serveur constitue uniquement une barrière au niveau du transport. À lui seul, il ne fournit pas l'identité utilisateur ou agent requise par la plupart des tools Stellary.

Étape 2 : configurer le client MCP

Utilisez les valeurs suivantes :

• Endpoint : https://api.stellary.co/mcp
• Transport : Streamable HTTP
• Header : Authorization: Bearer VOTRE_TOKEN
• Identifiant de session MCP persistant : non requis

Pour les clients qui utilisent un objet JSON mcpServers :

{
  "mcpServers": {
    "stellary": {
      "url": "https://api.stellary.co/mcp",
      "headers": {
        "Authorization": "Bearer VOTRE_TOKEN"
      }
    }
  }
}

Pour Claude Code :

claude mcp add stellary \
  --transport streamable-http \
  https://api.stellary.co/mcp \
  --header "Authorization: Bearer VOTRE_TOKEN"

Le format de configuration peut évoluer selon le client. Conservez l'endpoint, le transport et le header ci-dessus, puis suivez la syntaxe actuelle de votre client.

Étape 3 : vérifier la connexion

Après la connexion, demandez au client de lister ses tools MCP. Effectuez ensuite un premier appel en lecture seule, par exemple list_projects.

Une vérification utile consiste à :

1. appeler list_projects ;
2. sélectionner un ID de projet exact ;
3. appeler list_cards ou get_project_details avec cet ID ;
4. vérifier que le workspace et le projet renvoyés correspondent au périmètre attendu.

Stellary sait résoudre certains noms, mais les IDs exacts sont plus sûrs pour les agents de longue durée et les workflows reproductibles.

Ce que le serveur MCP de Stellary expose

La liste disponible dépend de l'identité connectée et des plugins installés. Les principales familles de tools sont :

• Lecture du board — list_projects, get_project_details, list_cards, get_card_details et get_card_comments ;
• Écriture et collaboration — create_card, move_card, update_card, assign_card et add_comment ;
• Cockpit et supervision — get_pilotage_state, get_cockpit_dashboard, get_agent_status et list_pending_proposals ;
• Runtime agent — stellary_init, get_next_mission, wait_for_mission, complete_mission et fail_mission ;
• Tools de plugins — intégrations workspace comme GitHub, Slack, Email, Discord ou X lorsque le plugin est installé, activé et accessible à l'agent.

La découverte des tools reste la source de vérité pour une connexion donnée. Un PAT, un agent token et un token de transport n'exposent pas les mêmes capacités.

Configurer les écritures avec précision

Pour les agent tokens, Stellary applique le mode d'autonomie configuré sur l'agent :

Un humain connecté avec un JWT ou un PAT agit en son nom ; les contrôles de proposition liés à l'autonomie concernent spécifiquement les agent tokens. Les permissions projet et les scopes du PAT continuent de limiter l'accès.

Commencez en lecture seule, vérifiez le contexte renvoyé, puis accordez uniquement les scopes et tools d'écriture nécessaires. Pour un nouvel agent ou un projet sensible, utilisez le mode approval tant que son comportement n'a pas été validé.

Dépannage

Le serveur renvoie une erreur 401

Vérifiez le format Bearer <token>, l'expiration ou la révocation du token, puis assurez-vous que le client transmet bien les headers personnalisés avec Streamable HTTP.

Un tool demande un user token

Vous utilisez probablement le MCP_TOKEN statique ou une connexion locale anonyme. Passez sur un JWT utilisateur ou un PAT.

Un tool demande un contexte workspace

Le tool est probablement réservé aux agents ou adossé à un plugin de workspace. Utilisez l'agent token associé au bon agent.

Une écriture devient une proposition

C'est le comportement attendu pour un agent en mode approval, ainsi que pour les tools protégés en mode supervised. Examinez la proposition dans Stellary ou modifiez la policy d'autonomie uniquement après avoir évalué le risque.

Un tool de plugin manque ou échoue

Vérifiez que le plugin est installé et activé dans le workspace, que sa configuration est complète et que l'agent connecté est autorisé à l'utiliser.

Une fois la connexion validée, utilisez les automatisations pour les règles événementielles déterministes, et MCP pour les clients interactifs ou les boucles d'agents qui ont besoin de contexte vivant et de découverte de tools.