Intégration MCP

Connectez vos outils IA à votre workspace Stellary via le Model Context Protocol. Consultez l'état de vos boards en temps réel, créez des cartes, gérez des documents et lancez des missions d'agents IA — le tout via un protocole standard que vos outils supportent déjà.

Comment ça fonctionne

Stellary expose un serveur MCP Streamable HTTP au chemin /mcp de l'URL de votre application. Aucun processus séparé ni installation nécessaire — il est intégré au backend Stellary.

Principes clés :

• Stateless : Chaque requête est indépendante — aucune persistance de session nécessaire
• Lecture + Écriture : L'IA peut lire les boards, créer/déplacer des cartes, gérer des documents
• Contrôle humain : Les agents supervisés proposent des modifications que les humains approuvent ou rejettent
• Correspondance floue : Les outils acceptent les noms de projets/colonnes/cartes avec tolérance aux fautes de frappe
• Accès limité : Les agents peuvent être restreints à des projets et des ensembles d'outils spécifiques

Guide de configuration

Vous avez besoin d'un token Bearer pour authentifier les requêtes MCP. Trois options sont disponibles :

Option A : Token d'accès personnel (recommandé)

1. Connectez-vous à Stellary
2. Allez dans Paramètres → Tokens API
3. Cliquez sur Créer un token
4. Sélectionnez les portées : projects:read, projects:write, pilotage:read
5. Copiez le token (affiché une seule fois)

Option B : Token JWT

Appelez l'endpoint de connexion et utilisez le access_token retourné :

curl -X POST https://app.stellary.co/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"vous@entreprise.com","password":"votre-mot-de-passe"}'

# Réponse : { "access_token": "eyJhbG...", ... }

Option C : Token MCP statique (lecture seule, test rapide)

Si l'administrateur de votre workspace a configuré un MCP_TOKEN statique, vous pouvez l'utiliser pour un accès en lecture seule. C'est utile pour des tests rapides mais ne prend pas en charge les opérations d'écriture.

# Utiliser le token statique
Authorization: Bearer votre-token-mcp

Configurer votre outil IA

Cursor

Créez ou modifiez .cursor/mcp.json à la racine de votre projet :

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

Puis dans Cursor : Settings → MCP → Refresh. Vous devriez voir « stellary » avec tous les outils disponibles listés.

Claude Desktop

Ajoutez à votre configuration MCP de Claude Desktop :

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

Claude Code

Ajoutez le serveur MCP Stellary via le CLI Claude Code :

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

Tout client MCP

Pointez votre client compatible MCP vers :

• URL : https://app.stellary.co/mcp
• Transport : Streamable HTTP (GET pour la découverte, POST pour les appels d'outils)
• En-tête : Authorization: Bearer VOTRE_TOKEN

Authentification

L'endpoint MCP prend en charge trois types de tokens, vérifiés dans cet ordre :

Toutes les requêtes MCP nécessitent un en-tête Authorization: Bearer valide. Les requêtes sans token valide sont rejetées avec un code 401.

Application du RBAC : L'accès aux outils est contrôlé par les rôles et permissions du workspace. Chaque outil déclare ses permissions requises (ex. task.create, document.read), et le moteur de politiques vérifie que l'utilisateur authentifié les possède avant l'exécution.

Agents IA

Les agents IA Stellary sont des utilisateurs bot rattachés à un workspace qui peuvent opérer sur vos boards et documents. Chaque agent est un utilisateur dédié avec sa propre identité, des outils configurables et des paramètres d'autonomie.

Créer un agent

Créez des agents dans l'interface Stellary sous les paramètres de votre workspace. Chaque agent possède :

• Nom et slug : Identifiant lisible (ex. « DevBot », dev-bot)
• Description : À quoi sert l'agent
• Outils : Liste blanche des IDs d'outils autorisés (vide = tous les outils disponibles)
• Mode d'autonomie : Contrôle la façon dont l'agent gère les opérations d'écriture
• Portée : Restreindre à des projets spécifiques
• Flag MCP-only : Lorsqu'il est activé, les missions sont mises en file d'attente au lieu d'être exécutées immédiatement

Modes d'autonomie

Les modes d'autonomie contrôlent comment l'agent gère les outils d'écriture et de collaboration. Les opérations de lecture sont toujours autorisées quel que soit le mode d'autonomie.

Référence des outils

Les outils sont organisés en quatre catégories. Chaque outil déclare ses permissions requises et son niveau de risque. Les outils exposés via MCP sont marqués avec la surface mcp.

Lecture Board

Outils en lecture seule pour explorer les projets, colonnes, cartes, commentaires, sous-tâches et labels.

Écriture Board

Outils pour créer, mettre à jour et déplacer des cartes. Nécessitent une authentification et des permissions d'écriture.

Collaboration Board

Outils pour assigner des cartes et ajouter des commentaires.

Opérations sur les documents

Outils pour lire et écrire des documents de projet dans le contexte d'une mission. Les documents sont rattachés au projet et peuvent être liés à des cartes.

Paramètres communs

La plupart des outils supportent la correspondance floue. Vous pouvez identifier les ressources par ID ou par nom :

La correspondance floue utilise la distance de Levenshtein avec une distance d'édition maximale de 2. Si aucune correspondance n'est trouvée, l'outil retourne les 3 meilleures suggestions avec des scores de confiance afin que l'IA puisse demander des clarifications à l'utilisateur.

Missions

Les missions sont des tâches IA au niveau des cartes, exécutées par des agents. Lorsque vous lancez une mission sur une carte, un agent planifie et exécute une séquence d'appels d'outils pour atteindre l'objectif décrit dans la carte.

Cycle de vie d'une mission

• En file d'attente : La mission est créée et attend l'exécution par l'agent (agents MCP-only)
• En cours : L'agent planifie et exécute activement des appels d'outils
• En attente d'approbation : L'agent supervisé a généré des propositions nécessitant une revue humaine
• Terminée : Toutes les étapes ont été exécutées avec succès, l'agent a produit un résumé
• Échouée : La mission a rencontré une erreur ou dépassé le budget

Streaming en temps réel (SSE)

La progression des missions est diffusée en temps réel via Server-Sent Events (SSE). Le flux d'événements inclut :

Chaque étape est persistée dans l'enregistrement MissionRun, de sorte que l'historique des missions est toujours disponible même après la fermeture de la connexion SSE.

Propositions

Lorsqu'un agent en mode supervisé ou approbation tente une opération d'écriture nécessitant une supervision humaine, il génère une proposition au lieu d'exécuter l'action directement.

Flux des propositions

1. L'agent appelle un outil d'écriture (ex. create_cards_bulk, create_mission_document)
2. Le moteur de politiques vérifie le mode d'autonomie de l'agent et le niveau de risque de l'outil
3. Si une approbation est requise, une proposition est créée avec l'ID de l'outil, les données d'entrée, le raisonnement et une date d'expiration
4. L'humain examine la proposition dans l'interface Stellary
5. Approuver : L'outil est exécuté avec les paramètres d'origine
6. Rejeter : La proposition est écartée, aucune action effectuée

Les données de la proposition incluent :

• ID de l'outil : Quel outil l'agent souhaite appeler
• Entrée : Les paramètres exacts que l'agent passerait
• Description : Ce que l'action ferait
• Résumé du raisonnement : Pourquoi l'agent souhaite effectuer cette action
• Expiration : Les propositions expirent si elles ne sont pas examinées à temps

Exemples d'utilisation

Explorer votre Board

> "Quel est l'état actuel de mon projet Q1 Launch ?"

L'IA appelle : list_projects
             → get_project_details(projectName: "Q1 Launch")
             → list_cards(projectName: "Q1 Launch")

L'IA répond : "Q1 Launch contient 12 cartes réparties sur 3 colonnes.
Le taux de complétion est de 42%. 2 cartes sont prioritaires et en retard..."

Créer des tâches à partir d'un cahier des charges

> "Crée des cartes pour le module de facturation basé sur le cahier des charges"

L'IA appelle : create_cards_bulk(projectName: "Q1 Launch", columnName: "To Do", cards: [
  { title: "Implémenter le handler webhook Stripe", priority: "high" },
  { title: "Ajouter les routes API de facturation", priority: "high" },
  { title: "Créer la génération de factures PDF", priority: "medium" },
  { title: "Écrire les tests d'intégration facturation", priority: "medium" }
])

Déplacer le travail terminé

> "Déplace la carte 'Migration du flux d'auth' vers Terminé"

L'IA appelle : move_card(projectName: "Q1 Launch", cardTitle: "Migration du flux d'auth", columnName: "Done")

Assigner et commenter

> "Assigne la carte des routes API à alice@company.com et ajoute un commentaire"

L'IA appelle : assign_card(projectName: "Q1 Launch", cardTitle: "Ajouter les routes API de facturation",
                       memberEmail: "alice@company.com")
             → add_comment(projectName: "Q1 Launch", cardTitle: "Ajouter les routes API de facturation",
                      content: "Assignée à Alice suite à la discussion de planification du sprint.")

Travailler avec les documents

> "Crée un brief technique pour la carte d'intégration paiement"

L'IA appelle : get_mission_documents(projectId: "...", cardId: "...")
             → create_mission_document(projectId: "...", cardId: "...",
                 title: "Brief Intégration Paiement",
                 content: "## Aperçu\n...",
                 docType: "brief")

Limitation de débit

Les requêtes MCP sont soumises aux limites de débit standard de l'API en fonction de votre plan. De plus, l'exécution des outils par les agents est régie par des politiques au niveau du workspace et de l'agent :

• Limites du plan workspace : Le nombre d'opérations IA par mois dépend de votre niveau d'abonnement
• Liste blanche d'outils de l'agent : Chaque agent peut être restreint à un sous-ensemble d'outils
• Portée du projet : Les agents peuvent être limités à des projets spécifiques — les appels d'outils ciblant d'autres projets sont rejetés
• Missions concurrentes : Une seule mission peut s'exécuter sur une carte à la fois ; les requêtes concurrentes reçoivent un 409 Conflict

Dépannage

401 Unauthorized

Votre token est invalide, expiré ou du mauvais type. Vérifiez :

• Le format de l'en-tête est-il correct ? Authorization: Bearer VOTRE_TOKEN
• Si vous utilisez un JWT : a-t-il expiré ? (par défaut : 7 jours)
• Si vous utilisez un PAT : est-il révoqué ? Vérifiez dans Paramètres → Tokens API
• Si vous utilisez un token MCP statique : correspond-il à la valeur configurée ?

403 Permission manquante

L'utilisateur authentifié ne possède pas la permission requise pour cet outil. Vérifiez votre rôle workspace et les requiredPermissions de l'outil (ex. task.create, document.read). Les tokens PAT doivent inclure les portées correspondantes.

L'outil retourne « Aucun projet trouvé »

L'utilisateur associé à votre token n'a aucun projet dans son workspace. Créez d'abord un projet via l'interface Stellary.

Appel d'outil de l'agent rejeté

Si l'appel d'outil d'un agent est rejeté, vérifiez :

• L'outil est-il dans la liste des outils autorisés de l'agent ?
• Le projet cible est-il dans la portée configurée de l'agent ?
• Le mode d'autonomie de l'agent autorise-t-il ce type d'opération ?

409 Conflict sur une mission

Une mission est déjà en cours d'exécution sur cette carte. Attendez que la mission actuelle se termine, ou vérifiez le statut de la mission dans l'interface Stellary.

Cursor n'affiche pas les outils MCP

• Vérifiez que l'URL dans .cursor/mcp.json est correcte : https://app.stellary.co/mcp
• Vérifiez que votre token est valide et dispose des permissions appropriées
• Cliquez sur Refresh dans les paramètres MCP de Cursor
• Consultez la console développeur de Cursor pour les erreurs de connexion

La correspondance floue retourne la mauvaise ressource

Utilisez l'ID exact (ex. projectId, cardId) au lieu d'un nom pour une correspondance précise. Récupérez les IDs depuis l'outil list_* correspondant.