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://api.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é

Une connexion OAuth appartient à un workspace et peut autoriser votre identité, un ou plusieurs agents actifs, ou les deux. Les credentials directs historiques restent pris en charge.

Appelez stellary_list_identities pour obtenir les références opaques. Avec une seule identité, actingAs est implicite. Avec plusieurs identités, actingAs est obligatoire sur chaque appel, y compris stellary_init et les tools de mission.

Authentification

OAuth 2.1 avec découverte, enregistrement dynamique des clients et PKCE S256 est le parcours public recommandé. Les clients reçoivent un access token d’une heure et peuvent renouveler leur connexion avec un refresh token rotatif lorsque offline_access est accordé.

L’accès est réévalué à chaque appel : scopes du credential, accès projet, permissions workspace, état et politique de l’agent, autonomie et snapshot de mission restent prioritaires. Un agent suspendu devient immédiatement indisponible sans couper les autres identités de la connexion.

Configuration client

Ajoutez seulement l’endpoint https://api.stellary.co/mcp dans un client OAuth compatible. Le client découvre automatiquement Stellary, ouvre la connexion dans votre navigateur, puis revient avec ses tokens. Aucun PAT n’est à copier dans sa configuration.

Cursor

{
  "mcpServers": {
    "stellary": {
      "url": "https://api.stellary.co/mcp"
    }
  }
}

Claude Code

claude mcp add stellary \
  --transport http \
  https://api.stellary.co/mcp

Claude Desktop et clients similaires

{
  "mcpServers": {
    "stellary": {
      "url": "https://api.stellary.co/mcp"
    }
  }
}

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.

Pour un client historique sans OAuth, créez un personal access token depuis la section API tokens et ajoutez-le comme bearer. OAuth reste le parcours recommandé pour toute nouvelle connexion.

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é

Un client OAuth doit suivre le challenge WWW-Authenticate et ouvrir le consentement Stellary. Pour un credential direct, vérifiez le format bearer, son expiration et sa révocation.

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

Avec plusieurs identités OAuth, appelez stellary_list_identities puis fournissez actingAs. Pour une action agent liée à un projet, réclamez d’abord une mission afin d’obtenir un missionRunId valide.

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.