Intégration MCP

MCP est le point d’entrée IA natif de Stellary et la meilleure façon de connecter Cursor, Claude Code, Claude Desktop, ou tout autre client Model Context Protocol à des données de delivery vivantes. Au lieu de reconstruire manuellement l’arbre REST, un client externe peut se brancher sur l’endpoint /mcp intégré et opérer à travers la même surface de tools que les agents et le runtime.

Cette page documente le comportement réel du serveur MCP actuellement implémenté dans le backend : transport, modèle d’identité, exposition du registre de tools, missions en file, gestion des propositions et extensions pilotées par plugins.

Vue d’ensemble

Le serveur MCP est intégré directement dans le backend NestJS. Il n’y a pas de daemon séparé à lancer, pas de sidecar à déployer, et pas de bridge custom à maintenir.

Endpoint: https://app.stellary.co/mcp
Transport: Streamable HTTP
Méthodes: GET et POST
Header auth: Authorization: Bearer <token>
Session requise: non

GET est utile pour la découverte / négociation de protocole.
POST transporte les vraies requêtes MCP.

L’implémentation crée un transport stateless neuf à chaque requête, notamment pour rester compatible avec les clients MCP qui ne persistent pas d’identifiant de session.

Besoin d’abord du setup produit plus large ? Commencez par le Démarrage rapide pour le workspace, les tokens et les agents, ou utilisez la Référence API si vous devez provisionner des ressources avant qu’un client IA n’entre dans la boucle.

MCP vs REST

Utilisez MCP lorsque l’appelant est un client IA ou une boucle agent. Utilisez REST lorsque vous avez besoin d’un CRUD ressource déterministe, de contrats HTTP explicites, ou d’une intégration backend classique.

Si vous devez créer workspaces, projets ou flux billing avant que la couche IA n’entre en jeu, partez de la Référence API puis ajoutez MCP par-dessus.

Transport

Le transport est volontairement stateless. En pratique, cela signifie que vous pouvez connecter des clients comme Cursor sans dépendre d’un Mcp-Session-Id persistant.

Modèle d’identité

Stellary MCP a deux modes de fonctionnement principaux : un utilisateur humain qui connecte un client IA, ou un agent de workspace dédié qui se connecte avec son propre token.

Cette distinction compte parce que certains tools ont besoin d’un contexte workspace. Les clients humains en JWT/PAT peuvent utiliser les flux board et cockpit, tandis que les agent tokens déverrouillent les tools avec contexte workspace comme les missions en file, les documents de mission et les intégrations plugins.

Authentification

Le contrôleur résout les bearer tokens par couches. D’abord un JWT utilisateur classique, ensuite un personal access token, puis en dernier recours le MCP_TOKEN statique optionnel.

L’accès aux tools est ensuite gouverné par l’accès projet, les permissions workspace, les whitelists d’agent, le scope projet et la politique d’autonomie. Pour les agent tokens, le comportement en écriture dépend du mode d’autonomie configuré.

Configuration client

Tous les clients MCP ont besoin des mêmes fondamentaux : l’endpoint https://app.stellary.co/mcp, le transport Streamable HTTP, et un header Authorization: Bearer.

Cursor

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

Claude Code

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

Claude Desktop et clients similaires

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

Après connexion, le premier mouvement utile consiste généralement à appeler list_projects, puis à passer sur des IDs exacts pour le reste de la session.

Si vous devez encore créer un personal access token ou un agent avant de connecter le client, suivez d’abord le Démarrage rapide et la section API tokens.

Workflows courants

En pratique, le serveur MCP de Stellary est surtout utilisé selon trois schémas : exploration interactive du workspace, exécution d’agent sur missions en file, et actions opérationnelles pilotées par plugins.

Pour les surfaces produit derrière ces workflows, voyez Board & cartes, Documents & contexte et le guide des agents.

Surface des tools

Les tools MCP sont assemblés depuis trois endroits dans le backend : les anciens tools cockpit, le registre partagé de tools cœur, et les plugins workspace installés. Le résultat est un endpoint unique, mais pas un usage unique.

Plusieurs tools board acceptent une commodité par nom avec résolution exacte ou fuzzy. Malgré cela, pour les runs sérieux et les boucles agent longues, mieux vaut découvrir les IDs d’abord puis les réutiliser explicitement.

Si vous voulez comprendre les surfaces humaines sur lesquelles ces tools opèrent, lisez aussi le guide board et le guide documents.

Tools plugins

Les définitions plugins sont enregistrées automatiquement dans la même surface MCP lorsque le plugin est installé et activé dans un workspace. Leurs IDs de tools sont préfixés par le slug du plugin.

Exemples:
github_list_repos
github_create_pr
slack_post_message
email_send_email
discord_post_message
x_create_draft

Le codebase embarque actuellement des définitions de plugins pour GitHub, Slack, Email, Discord et X. Ces tools demandent un contexte workspace plus une configuration plugin déchiffrée, donc ils sont typiquement consommés via des agent tokens.

Missions agent

MCP devient particulièrement puissant lorsqu’il est couplé à des agents de workspace dédiés. Dans ce modèle, l’app met les missions en file et le client MCP externe devient la boucle d’exécution.

1. Assignez un agent actif à une carte dans Stellary.
2. Lancez une mission depuis l’app.
3. Si l’agent est mcpOnly, la mission est mise en file au lieu d’être exécutée localement.
4. Le client MCP externe réclame le travail avec get_next_mission ou long-poll avec wait_for_mission.
5. La prise en charge passe la mission en cours et déplace la carte vers la colonne in-progress si possible.
6. Le client termine avec complete_mission ou fail_mission, ce qui met à jour l’état de mission et poste un commentaire sur la carte.

Pour les agent tokens, stellary_init est l’appel de bootstrap recommandé. Il retourne le mode d’autonomie, les règles, les skills, et la liste filtrée des tools réellement disponibles pour cet agent.

Boucle agent recommandée:
1. stellary_init
2. get_next_mission ou wait_for_mission
3. lire le contexte carte et les documents
4. exécuter les tools avec des IDs exacts
5. complete_mission ou fail_mission

Approbations

Le comportement de proposition est piloté par la couche de policy des tools. Seuls les agent tokens participent aux contrôles de propositions liés à l’autonomie ; un humain utilisant MCP agit directement en son nom.

Les agents MCP-only gardent le mode d’autonomie configuré dans Stellary. En mode approval, les écritures non-read deviennent des propositions persistées, même si le client d’exécution est externe.

Développement local

En développement local, si NODE_ENV n’est pas `production` et que MCP_TOKEN n’est pas défini, le contrôleur laisse les requêtes non authentifiées atteindre le transport MCP. Cela simplifie le branchement local, mais ne donne pas magiquement accès aux données workspace.

Exemple backend/.env:
# MCP_TOKEN=your-secret-token

Sans MCP_TOKEN en local :
- /mcp reste joignable
- les tools workspace actuels demandent encore majoritairement une identité utilisateur ou agent

En production, ou dès que MCP_TOKEN est configuré, un bearer token est requis avant même d’atteindre le transport.

Dépannage

401 token invalide ou expiré

Vérifiez d’abord le format du bearer. Ensuite, confirmez que vous utilisez un JWT utilisateur, un PAT, ou un agent token qui existe encore et n’a pas été révoqué.

Le tool indique qu’il faut un user token

Vous êtes probablement connecté avec MCP_TOKEN ou avec une requête locale anonyme. Passez sur un JWT utilisateur ou un personal access token.

Le tool indique qu’il faut un contexte workspace

Cela signifie généralement que vous essayez d’appeler un tool réservé aux agents ou adossé à un plugin depuis une session humaine JWT/PAT. Utilisez plutôt un agent token rattaché à un agent de workspace.

Le tool plugin est visible mais échoue

Le plugin du workspace n’est peut-être pas installé ou activé, ou sa configuration chiffrée peut être manquante. Les tools plugins demandent aussi un contexte agent/workspace dans le flow MCP actuel.

Le fuzzy matching choisit la mauvaise ressource

Commencez par list_projects, list_cards, ou un autre tool de découverte, puis réutilisez les IDs exacts. C’est le pattern le plus sûr pour des boucles agent longues.

Guides liés

Ces pages aident à relier MCP au reste du modèle opératoire Stellary, du provisioning des ressources jusqu’aux agents de workspace et à une stratégie MCP plus large.