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

Canopy 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 Canopy (:8001, interne)
    │
    │  OAuth 2.1 avec PKCE
    │  délègue au fournisseur SSO
    ▼
Backend Canopy (: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 Canopy de l'utilisateur). Le jeton est renouvelé de manière proactive environ une heure avant son expiration.
L'outil IA utilise ce jeton pour toutes les requêtes suivantes.
Chaque requête passe par le système de permissions normal de Canopy — 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 -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 — si le conteneur n'est pas en cours d'exécution, les requêtes reçoivent une réponse 502 propre plutôt que de faire planter le proxy périphérique.

Étape 2 : Configurer les variables d'environnement

Ajoutez celles-ci à votre fichier .env :

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

Variable	Défaut	Description
`CANOPY_URL`	`http://backend:8000`	URL interne du backend à laquelle le conteneur MCP s'adresse (nom du service Docker — a rarement besoin d'être modifiée).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	L'URL publique de votre instance Canopy.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	L'URL publique du serveur MCP (utilisée dans les URIs de redirection OAuth et les métadonnées).
`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 Canopy), 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.

attention

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 et mettre à jour vos données EA.

VS Code (GitHub Copilot / Cursor)

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

{
  "servers": {
    "canopy": {
      "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": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}

Dans ce mode, le serveur s'authentifie directement avec l'email et le mot de passe (sans OAuth) et renouvelle automatiquement le JWT Canopy en arrière-plan.

Capacités disponibles

Le serveur MCP expose 47 outils : 30 outils de lecture répartis en neuf clusters, et 17 outils d'écriture (13 additifs, 4 destructifs). Chaque outil porte des ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint) afin que les connecteurs comme Claude Desktop puissent signaler le caractère destructif d'un appel dans leur interface avant qu'un utilisateur ne l'approuve.

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é.

Pour les validations plus importantes, un second verrou s'applique : toute validation portant sur plus de MCP_BATCH_CONFIRMATION_THRESHOLD lignes (20 par défaut) doit renvoyer un confirm_token à usage unique émis par l'exécution à blanc précédente. Ce jeton a une durée de vie de 15 minutes. Ce contrôle est appliqué deux fois — une première fois par le wrapper MCP avant même d'appeler le backend, puis une seconde fois par le backend lui-même sur le point de terminaison de validation — afin qu'un client qui saute l'étape d'exécution à blanc ne puisse pas faire passer un lot important sans revue.

Lots de mutation (piste d'audit)

Chaque appel d'écriture — exécution à blanc ou non — ouvre une ligne mutation_batches avant de toucher la moindre donnée, et chaque événement qu'il émet (fiche créée, relation créée/mise à jour, commentaire publié, …) est étiqueté avec l'identifiant de ce lot, le nom de l'outil appelant et l'utilisateur authentifié. L'outil get_change_history reconstruit le diff complet, événement par événement, d'un lot à partir de son identifiant, et rollback_batch peut annuler les écritures d'un lot (voir ci-dessous). Cela signifie que toute modification pilotée par MCP peut être retracée jusqu'à savoir exactement qui a exécuté quel outil et quand — ce qui la distingue de la même action effectuée via l'interface web.

Outils de lecture

Le serveur expose 30 outils de lecture, répartis en neuf 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 les enfants d'une fiche
`list_card_types`	Lister tous les types de fiche du métamodèle, avec leurs champs et leur configuration
`get_relation_types`	Lister les types de relation, avec filtre optionnel par type de fiche
`resolve_card_refs`	Pré-valider les références de fiches basées sur le nom (ex. « Sales / Customer Mgmt / CRM ») avant un import en masse — fait remonter les correspondances résolues / ambiguës / manquantes
`analyze_impact`	Analyse d'impact multi-sauts — parcourt le graphe de relations à partir d'une fiche jusqu'à 3 sauts, regroupés par profondeur, avec filtres optionnels par type de relation et 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 probabilité × impact
`get_card_risks`	Tous les risques actuellement liés à une fiche donnée

GRC — Conformité

Outil	Description
`list_compliance_findings`	Constats de conformité regroupés par régulation (EU AI Act, RGPD, NIS2, DORA, SOC 2, ISO 27001)
`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 / fiche / statut / recherche
`get_adr`	ADR unique avec sections, fiches liées, ADR associés 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 (fit fonctionnel × technique par défaut)
`get_cost_treemap`	Treemap des coûts d'une fiche, 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 à une fiche
`get_card_comments`	Fil de commentaires d'une fiche
`get_card_documents`	Liens documentaires attachés à une fiche

Diagrammes

Outil	Description
`list_diagrams`	Lister les diagrammes libres, avec filtre optionnel sur une fiche
`get_diagram`	Récupérer un diagramme unique par son identifiant, y compris son XML DrawIO

Audit et historique des modifications

Outil	Description
`get_change_history`	Rechercher un lot de mutation par son identifiant (renvoie le lot et chaque événement qui y a été émis, dans l'ordre), ou parcourir les lots récents par acteur, nom d'outil ou origine (`mcp` / `web` / `api`)

Tous les outils de lecture sont soumis au RBAC de l'utilisateur authentifié — un visualiseur recevra simplement une liste vide (ou une erreur 403) pour les zones qu'il ne peut pas voir ; rien n'a besoin d'être configuré par outil au niveau MCP.

Outils d'écriture

Le serveur expose 17 outils d'écriture : 13 additifs (actions de création/mise à jour qui ne détruisent pas de données) et 4 destructifs (peuvent écraser ou supprimer des données, bien que plusieurs d'entre eux restent eux-mêmes récupérables — voir les notes ci-dessous).

Fiches & cycle de vie

Outil	Annotation	Description
`create_cards_bulk`	Additif	Crée plusieurs fiches en un seul appel à partir de lignes extraites d'un artefact (ex. 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.
`update_cards_bulk`	Additif	Met à jour plusieurs fiches en un seul appel — correctifs au niveau des champs avec un diff avant/après par ligne lors de l'exécution à blanc. `attributes` remplace intégralement les attributs de chaque ligne ; `strict_attributes=true` rejette les clés de champ inconnues avec une indication de correction.
`transition_card_lifecycle`	Additif	Fait progresser une fiche via des actions d'approbation (`approve` / `reject` / `reset`), des phases de cycle de vie (`phaseIn` / `active` / `phaseOut` / `endOfLife`) ou des valeurs de statut (`ACTIVE` / `PHASING_IN` / `PHASING_OUT` / `END_OF_LIFE` / `ARCHIVED`). Renvoie une réponse `pending` avec un lien direct vers l'interface si l'appelant n'a pas la permission requise, plutôt que d'échouer purement et simplement.
`archive_cards`	Destructif	Archive (suppression réversible) une ou plusieurs fiches, avec un aperçu de la cascade lors de l'exécution à blanc (enfants, relations orphelines). Les fiches archivées restent récupérables pendant 30 jours avant purge automatique. La suppression définitive n'est volontairement pas exposée via MCP.

Relations & diagrammes

Outil	Annotation	Description
`upsert_relations_bulk`	Destructif	Crée ou supprime des relations entre fiches. `action: "delete"` est refusée par défaut (voir les garde-fous ci-dessous) — c'est ce qui vaut à cet outil son annotation destructive, même si la création est le cas d'usage courant.
`create_diagram`	Additif	Crée un diagramme DrawIO libre, avec des liens optionnels vers des fiches existantes par UUID.
`update_diagram`	Destructif	Met à jour le XML, le nom, la description ou les fiches liées d'un diagramme existant — `drawio_xml` remplace le contenu du canevas tel quel.
`import_bpmn`	Additif	Enregistre un diagramme BPMN 2.0 sur une fiche Processus métier existante, en suivant le flux brouillon → soumission → approbation. Si aucune fiche correspondante n'existe, renvoie une erreur `card_not_found` qui pointe vers `create_cards_bulk` plutôt que de créer silencieusement une fiche incomplète.

GRC — Registre des risques

Outil	Annotation	Description
`create_risks`	Additif	Crée un ou plusieurs risques, avec possibilité de lier les fiches concernées dans le même appel.
`update_risks`	Additif	Met à jour des risques existants par identifiant ; `linked_card_ids` remplace l'ensemble des fiches liées lorsqu'il est fourni.

Gouvernance & livraison

Outil	Annotation	Description
`create_soaw`	Additif	Crée un Statement of Architecture Work pour une initiative.
`create_adr`	Additif	Crée un Architecture Decision Record (créé à l'état `draft` par défaut).
`update_adr`	Additif	Met à jour le titre, les sections, le statut ou les fiches liées d'un ADR existant.
`sign_adr`	Additif	Signe un ADR. Renvoie une réponse `pending` avec un lien direct si l'appelant n'a pas la permission `adr.sign`.

Collaboration

Outil	Annotation	Description
`add_card_comment`	Additif	Publie un commentaire (optionnellement en fil) sur une fiche.
`assign_stakeholders`	Additif	Affecte ou retire des rôles de partie prenante sur des fiches. Le backend ne dispose pas de point de terminaison en masse pour cela ; l'outil éclate donc les opérations une par une au sein d'un même lot de mutation.

Audit

Outil	Annotation	Description
`rollback_batch`	Destructif	Annule les écritures effectuées sous un lot de mutation en parcourant ses événements en sens inverse et en appliquant l'inverse de chacun. Couvre `card.created` / `card.updated` / `card.archived` / `card.restored` / `relation.created` / `relation.upserted` ; les autres types d'événements apparaissent comme `unsupported_events` dans le plan d'exécution à blanc. L'annulation elle-même est enregistrée comme un nouveau lot, si bien que l'historique n'est jamais effacé. Refuse l'opération si un lot ultérieur a touché les mêmes entités, sauf si `force=true`, ce qui nécessite la permission `admin.events`.

Le contenu stocké par ces outils (corps de commentaires, texte des sections ADR/SoAW) est traité comme des données non fiables lors d'une relecture ultérieure — le serveur ne l'interprète jamais comme des instructions, il se contente de l'afficher.

Flux typique d'import d'artefact

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 analyse le tableur (dans son propre contexte, pas dans MCP) et construit des dictionnaires de ligne.
Facultativement, l'agent appelle resolve_card_refs pour vérifier que les références de parent/relation basées sur le nom se résolvent sans ambiguïté.
L'agent appelle create_cards_bulk(cards=…, dry_run=True) et présente l'aperçu à l'utilisateur.
L'utilisateur confirme ; l'agent rappelle l'outil avec dry_run=False (en renvoyant confirm_token si le lot dépasse le seuil de confirmation) 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.

Le serveur MCP lui-même ne parse jamais les fichiers téléversés — l'outil d'IA appelant lit l'artefact source (tableur, XML BPMN, XML DrawIO, PDF, image) dans son propre contexte et envoie des lignes déjà structurées.

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 :

Plafonds de taille par appel. Les outils d'écriture MCP appliquent un plafond bien plus bas que les points de terminaison sous-jacents de l'importateur Excel : 200 fiches pour create_cards_bulk / update_cards_bulk / archive_cards, 500 opérations pour upsert_relations_bulk. Suffisamment grand pour tout téléversement d'artefact unique réaliste, suffisamment petit pour qu'un aperçu d'exécution à blanc reste consultable d'un coup d'œil. Les points de terminaison backend eux-mêmes acceptent jusqu'à 2000/5000 pour l'importateur Excel légitime de l'interface web.
Jeton de confirmation au-delà du seuil. Les validations touchant plus de MCP_BATCH_CONFIRMATION_THRESHOLD lignes (20 par défaut) doivent renvoyer le confirm_token émis par l'exécution à blanc précédente. Contrôle appliqué à la fois par le wrapper MCP et par le backend.
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 avec une piste d'audit explicite. Les opérateurs peuvent activer cette possibilité avec MCP_ALLOW_RELATION_DELETE=true.
Pas de suppression définitive. L'ensemble d'outils omet volontairement la suppression permanente de fiches. archive_cards (suppression réversible, fenêtre de restauration de 30 jours) et rollback_batch sont les seuls moyens de supprimer des données via MCP, et les deux sont soumis à l'exécution à blanc et annotés comme destructifs. Tout futur outil effectuant une mutation irréversible nécessite d'abord une discussion RFC.
Interrupteur d'arrêt. MCP_WRITES_ENABLED=false désactive les 17 outils d'écriture sans redéployer de code. Les 30 outils de lecture continuent de fonctionner.
Étiquette d'origine d'audit. Chaque requête backend émise par le serveur MCP transporte un en-tête X-Canopy-Origin: mcp (liste blanche côté serveur limitée à {mcp, web, api} — toute autre valeur est rejetée). Les événements émis depuis ces requêtes sont étiquetés origin: "mcp" dans le payload d'audit, ce qui permet aux administrateurs de filtrer les écritures pilotées par MCP dans la chronologie. L'en-tête X-Canopy-Batch propage l'identifiant du lot de mutation en cours à travers tous les appels d'une même invocation d'outil.

Les 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 par appel pour `create_cards_bulk`, `update_cards_bulk`, `archive_cards`.
`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"`.
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	Nombre de lignes au-delà duquel une validation doit renvoyer un `confirm_token` émis par une exécution à blanc précédente.
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	Lorsque `true`, une validation dépassant le seuil sans exécution à blanc préalable correspondante dans la même session est rejetée. Les opérateurs peuvent désactiver ce contrôle pour des pipelines d'automatisation de confiance.

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	Configure 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 la permission backend correspondant à l'action qu'ils effectuent.

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'interface d'inventaire, il ne peut pas non plus en créer via MCP ; il n'existe pas de permissions de données spécifiques à MCP. Sélection de permissions par outil :

Permission	Contrôle
`inventory.create`	`create_cards_bulk`
`inventory.edit`	`update_cards_bulk`, transitions de cycle de vie/statut via `transition_card_lifecycle`
`inventory.approval_status`	Transitions d'approbation (`approve` / `reject` / `reset`) via `transition_card_lifecycle`
`inventory.archive`	`archive_cards`
`relations.manage`	`upsert_relations_bulk`
`diagrams.manage`	`create_diagram`, `update_diagram`
`bpm.edit`	`import_bpmn` (rédaction) ; la publication nécessite en plus `card.approval_status` sur le processus, détenue via le rôle de partie prenante `process_owner`, admin, ou bpm_admin
`risks.manage`	`create_risks`, `update_risks`
`comments.create`	`add_card_comment`
`stakeholders.manage`	`assign_stakeholders`
`soaw.create`	`create_soaw`
`adr.create`	`create_adr`, `update_adr`
`adr.sign`	`sign_adr`
`admin.events`	`rollback_batch(force=True)` — pour outrepasser un conflit d'annulation avec un lot ultérieur

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.

Plusieurs outils d'écriture se dégradent avec élégance plutôt que d'échouer purement et simplement lorsque l'appelant n'a pas la permission requise : transition_card_lifecycle et sign_adr renvoient une réponse pending avec un lien direct vers l'interface web afin qu'un humain disposant de la bonne permission puisse y terminer l'action.

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 (en mode HTTP).
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 requête MCP — lecture ou écriture — s'exécute avec les permissions de l'utilisateur authentifié. Aucun compte de service partagé.
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 auditée sous l'identité de l'utilisateur dans le cadre d'un lot de mutation.
Verrou par jeton de confirmation sur les validations importantes : Les validations dépassant le seuil configurable de lignes exigent un jeton émis par une exécution à blanc précédente, vérifié indépendamment par le wrapper MCP et par le backend.
Piste d'audit complète avec annulation : get_change_history reconstruit le diff de n'importe quel lot à partir de son identifiant ; rollback_batch peut annuler les types d'événements pris en charge d'un lot, cette annulation étant elle-même enregistrée comme un nouveau lot auditable.
Aucune 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 analyse dans son propre contexte et envoie des lignes structurées. Cela maintient une surface d'attaque réduite et évite d'exposer le serveur à des entrées binaires malformées.
Pas de suppression définitive via MCP : La suppression permanente de fiches n'est exposée par aucun outil. Les seuls chemins de suppression sont archive_cards (suppression réversible avec récupération sous 30 jours) et rollback_batch.
Rotation des jetons : Les jetons d'accès expirent après 1 heure et sont renouvelés de manière proactive. 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.
Stockage des jetons sur une seule instance : Les jetons OAuth sont conservés en mémoire sur le conteneur MCP. Si vous exécutez plusieurs répliques derrière un équilibreur de charge, épinglez les sessions à une seule instance ou attendez-vous à ce que les utilisateurs doivent se réauthentifier après un basculement — les jetons ne sont pas partagés entre répliques.

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 avec élégance (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.
Un outil d'écriture renvoie `writes_disabled`	`MCP_WRITES_ENABLED=false` sur ce déploiement. Les outils de lecture continuent de fonctionner ; demandez à un opérateur de réactiver les écritures si nécessaire.
Validation rejetée avec `confirm_token_required`	Le lot dépasse le nombre de lignes défini par `MCP_BATCH_CONFIRMATION_THRESHOLD`. Relancez d'abord avec `dry_run=true`, puis renvoyez le `confirm_token` obtenu lors de l'appel de validation.
La connexion s'interrompt après 1 heure	L'outil IA devrait gérer le renouvellement du jeton automatiquement. Sinon, reconnectez-vous.

Fonctionnement​

Prérequis​

Configuration​

Étape 1 : Démarrer le service MCP​

Étape 2 : Configurer les variables d'environnement​

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

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

Connecter les outils IA​

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

Test local (mode stdio)​

Capacités disponibles​

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

Lots de mutation (piste d'audit)​

Outils de lecture​

Outils d'écriture​

Flux typique d'import d'artefact​

Garde-fous des outils d'écriture​

Ressources​

Prompts guidés​

Permissions​

Sécurité​

Dépannage​