Intégration MCP (accès pour outils IA)¶

Turbo EA inclut un serveur MCP (Model Context Protocol) intégré qui permet aux outils d'IA — tels que Claude Desktop, GitHub Copilot, Cursor et VS Code — d'interroger et de mettre à jour vos données EA directement. Les outils d'IA peuvent aussi téléverser des artefacts (tableurs, diagrammes BPMN, diagrammes DrawIO, documents libres) et les transformer en fiches, relations et diagrammes conformes au métamodèle existant. Les utilisateurs s'authentifient via leur fournisseur SSO existant, et chaque action respecte leurs permissions individuelles.

Cette fonctionnalité est optionnelle et ne démarre pas automatiquement. Elle nécessite que le SSO soit configuré, que le profil MCP soit activé dans Docker Compose et qu'un administrateur l'active dans l'interface de configuration.

Fonctionnement¶

Outil IA (Claude, Copilot, etc.)
    │
    │  Protocole MCP (HTTP + SSE)
    ▼
Serveur MCP Turbo EA (:8001, interne)
    │
    │  OAuth 2.1 avec PKCE
    │  délègue au fournisseur SSO
    ▼
Backend Turbo EA (:8000)
    │
    │  RBAC par utilisateur
    ▼
PostgreSQL

Un utilisateur ajoute l'URL du serveur MCP à son outil IA.
Lors de la première connexion, l'outil ouvre une fenêtre de navigateur pour l'authentification SSO.
Après la connexion, le serveur MCP émet son propre jeton d'accès (adossé au JWT Turbo EA de l'utilisateur).
L'outil IA utilise ce jeton pour toutes les requêtes suivantes. Les jetons se renouvellent automatiquement.
Chaque requête passe par le système de permissions normal de Turbo EA — les utilisateurs ne voient que les données auxquelles ils ont accès.

Prérequis¶

Avant d'activer MCP, vous devez avoir :

SSO configuré et fonctionnel — MCP délègue l'authentification à votre fournisseur SSO (Microsoft Entra ID, Google Workspace, Okta ou OIDC générique). Consultez le guide Authentification et SSO.
HTTPS avec un domaine public — Le flux OAuth nécessite une URI de redirection stable. Déployez derrière un proxy inverse avec terminaison TLS (Caddy, Traefik, Cloudflare Tunnel, etc.).

Configuration¶

Étape 1 : Démarrer le service MCP¶

Le serveur MCP est un profil optionnel de Docker Compose. Ajoutez --profile mcp à votre commande de démarrage :

docker compose --profile mcp up --build -d

Cela démarre un conteneur Python léger (port 8001, interne uniquement) aux côtés du backend et du frontend. Nginx redirige automatiquement les requêtes /mcp/ vers celui-ci.

Étape 2 : Configurer les variables d'environnement¶

Ajoutez celles-ci à votre fichier .env :

TURBO_EA_PUBLIC_URL=https://votre-domaine.exemple.com
MCP_PUBLIC_URL=https://votre-domaine.exemple.com/mcp

Variable	Défaut	Description
`TURBO_EA_PUBLIC_URL`	`http://localhost:8920`	L'URL publique de votre instance Turbo EA
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	L'URL publique du serveur MCP (utilisée dans les URIs de redirection OAuth)
`MCP_PORT`	`8001`	Port interne du conteneur MCP (rarement besoin de changer)

Étape 3 : Ajouter l'URI de redirection OAuth à votre application SSO¶

Dans l'enregistrement d'application de votre fournisseur SSO (le même que celui configuré pour la connexion Turbo EA), ajoutez cette URI de redirection :

https://votre-domaine.exemple.com/mcp/oauth/callback

Ceci est nécessaire pour le flux OAuth qui authentifie les utilisateurs lorsqu'ils se connectent depuis leur outil IA.

Étape 4 : Activer MCP dans les paramètres d'administration¶

Allez dans Paramètres dans la zone d'administration et sélectionnez l'onglet AI.
Faites défiler jusqu'à la section Intégration MCP (Accès aux outils IA).
Activez le commutateur pour activer MCP.
L'interface affichera l'URL du serveur MCP et les instructions de configuration à partager avec votre équipe.

Warning

Le commutateur est désactivé si le SSO n'est pas configuré. Configurez d'abord le SSO.

Connecter les outils IA¶

Une fois MCP activé, partagez l'URL du serveur MCP avec votre équipe. Chaque utilisateur l'ajoute à son outil IA :

Claude Desktop¶

Ouvrez Paramètres > Connecteurs > Ajouter un connecteur personnalisé.
Entrez l'URL du serveur MCP : https://votre-domaine.exemple.com/mcp
Cliquez sur Connecter — une fenêtre de navigateur s'ouvre pour la connexion SSO.
Après l'authentification, Claude peut interroger vos données EA.

VS Code (GitHub Copilot / Cursor)¶

Ajoutez à votre .vscode/mcp.json d'espace de travail :

{
  "servers": {
    "turbo-ea": {
      "type": "http",
      "url": "https://votre-domaine.exemple.com/mcp/mcp"
    }
  }
}

Le double /mcp/mcp est intentionnel — le premier /mcp/ est le chemin du proxy Nginx, le second est le point de terminaison du protocole MCP.

Test local (mode stdio)¶

Pour le développement local ou les tests sans SSO/HTTPS, vous pouvez exécuter le serveur MCP en mode stdio — Claude Desktop le lance directement comme processus local.

1. Installer le paquet du serveur MCP :

pip install ./mcp-server

2. Ajouter à la configuration de Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "votre@email.com",
        "TURBO_EA_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}

Dans ce mode, le serveur s'authentifie avec email/mot de passe et renouvelle le jeton automatiquement en arrière-plan.

Capacités disponibles¶

Le serveur MCP expose 30 outils répartis en deux groupes : 25 outils de lecture qui interrogent les données EA et 5 outils d'écriture qui transforment les artefacts qu'un outil d'IA a dans son propre contexte (tableurs, BPMN XML, DrawIO XML, documents, images) en fiches, relations et diagrammes.

Sécurité par exécution à blanc lors des écritures¶

Chaque outil d'écriture utilise par défaut dry_run=true. Dans ce mode, le backend exécute chaque validateur et résolveur, construit le plan complet puis annule la transaction afin que rien ne soit persisté. L'outil d'IA renvoie l'aperçu à l'utilisateur ; ce n'est qu'après confirmation explicite qu'il doit rappeler l'outil avec dry_run=false pour valider. Cela empêche un agent trop zélé d'introduire silencieusement des centaines de fiches à partir d'un tableur mal interprété.

Outils de lecture¶

Le serveur expose 25 outils de lecture, regroupés en six clusters.

Fiches & métamodèle

Outil	Description
`search_cards`	Rechercher et filtrer les fiches par type, statut ou texte libre
`get_card`	Obtenir les détails complets d'une fiche par UUID
`get_card_relations`	Obtenir toutes les relations connectées à une fiche
`get_card_hierarchy`	Obtenir les ancêtres et enfants d'une fiche
`list_card_types`	Lister tous les types de fiche du métamodèle
`get_relation_types`	Lister les types de relation, avec filtre optionnel par type de fiche

Tableaux de bord

Outil	Description
`get_dashboard`	Tableau de bord KPI (comptages, qualité des données, approbations, activité)
`get_landscape`	Fiches d'un type regroupées par un type lié

GRC — Registre des risques

Outil	Description
`list_risks`	Liste paginée et filtrable du registre des risques EA (TOGAF Phase G)
`get_risk`	Détail d'un risque avec fiches liées et piste d'audit
`get_risk_metrics`	KPIs + matrices 4×4 initiales et résiduelles
`get_card_risks`	Tous les risques actuellement liés à une fiche

GRC — Conformité

Outil	Description
`list_compliance_findings`	Constats de conformité regroupés par régulation
`get_compliance_overview`	Scores de conformité + matrice de statut par régulation + métadonnées du dernier scan

Gouvernance & Livraison

Outil	Description
`list_principles`	Principes EA publiés (énoncé, justification, implications)
`list_adrs`	Architecture Decision Records, filtrables par initiative / statut
`get_adr`	ADR unique avec sections, fiches liées et piste de signature
`list_soaws`	Statements of Architecture Work d'une initiative

Rapports

Outil	Description
`get_portfolio_report`	Données du graphique à bulles pour un type de fiche (défaut : fit fonctionnel × technique)
`get_cost_treemap`	Treemap des coûts, optionnellement groupé par un type lié
`get_capability_heatmap`	Heatmap hiérarchique des capacités métier
`get_data_quality_report`	Ventilation de la complétude par type de fiche

Contexte de fiche

Outil	Description
`get_card_stakeholders`	Utilisateurs + rôles affectés à la fiche
`get_card_comments`	Fil de commentaires d'une fiche
`get_card_documents`	Liens documentaires attachés à une fiche (URL, pas de fichiers)

Tous les outils respectent le RBAC de l'utilisateur authentifié — un visualiseur recevra simplement une liste vide (ou 403) pour ce qu'il ne peut pas voir ; aucune configuration par outil n'est nécessaire au niveau MCP.

Outils d'écriture — téléversement d'artefacts¶

Cinq outils permettent à un agent d'IA de transformer des artefacts en données EA structurées. L'agent lit le fichier source dans son propre contexte (vision multimodale, pièces jointes), extrait des lignes structurées et appelle ces outils. Le serveur MCP lui-même ne parse jamais les fichiers — il attend des entrées déjà structurées.

Outil	Description
`create_cards_bulk`	Crée plusieurs fiches en un seul appel (par exemple lignes de tableur). Prend en charge les références au parent par nom au sein du même lot, avec tri topologique côté serveur.
`resolve_card_refs`	Pré-valide les références basées sur le nom avant un import en masse — utile pour faire remonter à l'utilisateur les parents ambigus ou manquants.
`upsert_relations_bulk`	Crée ou supprime des relations entre fiches. Source / cible / type sont validés contre le métamodèle.
`create_diagram`	Crée un diagramme DrawIO libre avec des liens optionnels vers des fiches existantes.
`import_bpmn`	Enregistre un diagramme XML BPMN 2.0 sur une fiche Processus métier existante. Si aucune fiche ne correspond au nom fourni, l'outil renvoie une erreur `card_not_found` qui renvoie l'agent vers `create_cards_bulk` — cela force la création explicite de la fiche avec description, sous-type et attributs au préalable, plutôt qu'un raccourci qui crée une fiche pauvre.

Flux typique lorsqu'un utilisateur partage un tableur avec l'agent d'IA :

L'agent appelle list_card_types et get_relation_types pour comprendre le métamodèle.
L'agent parse le tableur (dans son propre contexte, pas dans MCP) et construit des dicts de ligne.
L'agent appelle create_cards_bulk(cards=…, dry_run=True) et montre l'aperçu à l'utilisateur.
L'utilisateur confirme ; l'agent rappelle avec dry_run=False pour valider.
Si des colonnes de relation sont présentes, l'agent appelle ensuite upsert_relations_bulk selon le même cycle exécution à blanc / confirmation.

Garde-fous des outils d'écriture¶

Défense en profondeur en plus de l'exécution à blanc, afin qu'une mauvaise interprétation du LLM ne puisse pas causer de dommages massifs :

Plafond de taille par appel. Les outils d'écriture MCP appliquent un plafond beaucoup plus petit que les endpoints sous-jacents de l'importateur Excel : 200 lignes pour create_cards_bulk, 500 opérations pour upsert_relations_bulk. Suffisamment grand pour tout téléversement d'artefact unique réaliste, suffisamment petit pour qu'une prévisualisation d'exécution à blanc reste scannable.
Pas de suppression de relation par défaut. upsert_relations_bulk refuse les opérations action: "delete" — pour supprimer des relations, utilisez l'interface web où l'action est consignée sous l'identité de l'utilisateur. Les opérateurs peuvent activer cette possibilité en définissant MCP_ALLOW_RELATION_DELETE=true.
Interrupteur d'arrêt. MCP_WRITES_ENABLED=false désactive les cinq outils d'écriture sans redéployer de code. Les 25 outils de lecture continuent de fonctionner.
Étiquette d'origine d'audit. Chaque requête backend du serveur MCP transporte un en-tête X-Turbo-EA-Origin: mcp. Les événements émis depuis ces requêtes sont étiquetés origin: "mcp" dans le payload du journal d'audit, ce qui permet aux administrateurs de filtrer les écritures pilotées par MCP hors de la chronologie, séparément des actions de l'interface web.
Pas d'outils de destruction massive. L'ensemble d'outils omet délibérément la suppression de fiche, l'archivage et la mise à jour en masse. L'ajout d'un tel outil nécessiterait une revue de conception explicite.

Les quatre variables d'environnement de garde-fou sur le conteneur MCP :

Variable	Défaut	Effet
`MCP_WRITES_ENABLED`	`true`	Interrupteur principal des outils d'écriture. `false` → MCP en lecture seule.
`MCP_MAX_CARDS_PER_CALL`	`200`	Plafond strict du nombre de lignes `create_cards_bulk` par requête.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Plafond strict du nombre d'opérations `upsert_relations_bulk` par requête.
`MCP_ALLOW_RELATION_DELETE`	`false`	Lorsque `true`, `upsert_relations_bulk` accepte les opérations `action: "delete"`.

Ressources¶

URI	Description
`turbo-ea://types`	Tous les types de fiche du métamodèle
`turbo-ea://relation-types`	Tous les types de relation
`turbo-ea://dashboard`	KPIs du tableau de bord et statistiques résumées

Prompts guidés¶

Prompt	Description
`analyze_landscape`	Analyse en plusieurs étapes : aperçu du tableau de bord, types, relations
`find_card`	Rechercher une fiche par nom, obtenir les détails et relations
`explore_dependencies`	Cartographier les dépendances d'une fiche

Permissions¶

Rôle	Accès
Administrateur	Configurer les paramètres MCP (permission `admin.mcp`). Accès complet en lecture + écriture via MCP.
Tous les utilisateurs authentifiés	Accès en lecture régi par leur RBAC existant. Les outils d'écriture exigent les permissions backend correspondantes — `inventory.create` (fiches), `relations.manage` (relations), `diagrams.manage` (diagrammes), `bpm.edit` (BPMN).

La permission admin.mcp contrôle qui peut gérer les paramètres MCP. Elle n'est disponible que pour le rôle Administrateur par défaut. Les rôles personnalisés peuvent recevoir cette permission via la page d'administration des Rôles.

L'accès aux données via MCP — en lecture ou en écriture — suit le même modèle RBAC que l'interface web. Si un utilisateur ne peut pas créer de fiches dans l'inventaire, il ne peut pas non plus en créer via MCP ; il n'y a pas de permissions de données spécifiques à MCP.

Sécurité¶

Authentification déléguée par SSO : Les utilisateurs s'authentifient via leur fournisseur SSO d'entreprise. Le serveur MCP ne voit ni ne stocke jamais les mots de passe.
OAuth 2.1 avec PKCE : Le flux d'authentification utilise Proof Key for Code Exchange (S256) pour empêcher l'interception des codes d'autorisation.
RBAC par utilisateur : Chaque action MCP — lecture ou écriture — s'exécute avec les permissions de l'utilisateur authentifié. Pas de comptes de service partagés.
Exécution à blanc par défaut sur les écritures : Les outils d'écriture proposent par défaut un aperçu valider-puis-annuler. L'outil d'IA doit rappeler explicitement avec dry_run=false avant qu'aucune donnée ne soit persistée, et chaque modification est journalisée sous l'identité de l'utilisateur.
Pas d'analyse de fichiers dans MCP : Le serveur MCP lui-même n'accepte pas de PDF, fichiers Excel, images ou autres artefacts binaires. L'outil d'IA appelant les parse dans son propre contexte et envoie des lignes structurées. Cela maintient la surface d'attaque réduite et évite d'exposer le serveur à des entrées binaires malformées.
Rotation des jetons : Les jetons d'accès expirent après 1 heure. Les jetons de renouvellement durent 30 jours. Les codes d'autorisation sont à usage unique et expirent après 10 minutes.
Port interne uniquement : Le conteneur MCP expose le port 8001 uniquement sur le réseau Docker interne. Tout accès externe passe par le proxy inverse Nginx.

Dépannage¶

Problème	Solution
Le commutateur MCP est désactivé dans les paramètres	Le SSO doit être configuré d'abord. Allez dans Paramètres > onglet Authentification et configurez un fournisseur SSO.
«host not found» dans les journaux Nginx	Le service MCP n'est pas en cours d'exécution. Démarrez-le avec `docker compose --profile mcp up -d`. La configuration Nginx gère cela gracieusement (réponse 502, pas de plantage).
Le callback OAuth échoue	Vérifiez que vous avez ajouté `https://votre-domaine.exemple.com/mcp/oauth/callback` comme URI de redirection dans l'enregistrement de votre application SSO.
L'outil IA ne peut pas se connecter	Vérifiez que `MCP_PUBLIC_URL` correspond à l'URL accessible depuis la machine de l'utilisateur. Assurez-vous que HTTPS fonctionne.
L'utilisateur obtient des résultats vides	MCP respecte les permissions RBAC. Si un utilisateur a un accès restreint, il ne verra que les fiches que son rôle autorise.
La connexion s'interrompt après 1 heure	L'outil IA devrait gérer le renouvellement des jetons automatiquement. Sinon, reconnectez-vous.