Aller au contenu principal
PlanRelevé Wiki

Intégrations API et MCP

PlanRelevé expose ses intégrations d'organisation par un point d'accès Model Context Protocol (MCP) sans état. Il permet à un client compatible d'interroger les projets PlanRelevé et, seulement si vous l'autorisez explicitement, de les modifier. Il utilise un jeton porteur : toute personne qui possède ce secret peut agir avec sa portée. La page d'administration n'émet pas de clé d'API REST générale distincte.

Page fictive Serveur MCP : activation de l'organisation, point d'accès, commande de configuration sans jeton réel, création d'un jeton en lecture seule et tableau des jetons, encore vide.
Page fictive Serveur MCP : activation de l'organisation, point d'accès, commande de configuration sans jeton réel, création d'un jeton en lecture seule et tableau des jetons, encore vide.

Prérequis et permissions

Chemin : menu du compte (votre initiale, en haut à droite) → Administration → Serveur MCP.

Seuls les rôles d'organisation Propriétaire et Admin peuvent ouvrir la page, activer MCP, créer et révoquer des jetons. Le client doit prendre en charge MCP par HTTP (Streamable HTTP) avec un en-tête Authorization: Bearer. Un jeton :

  • est limité à l'organisation de son créateur;
  • agit comme la personne qui l'a créé, pas comme un nouveau compte de service;
  • voit ses permissions de projet revérifiées à chaque appel;
  • est en Lecture seule sauf si Autoriser les outils d'écriture (jeton lecture-écriture) a été coché;
  • cesse de fonctionner s'il est révoqué, si son créateur est désactivé, supprimé ou quitte l'organisation, ou tant que MCP est désactivé pour l'organisation.

MCP est désactivé au niveau de l'organisation par défaut. Le jeton est accepté seulement sur /mcp et /mcp/files; ce n'est pas une clé générale pour les routes Web ou l'API interne de l'application.

Activer le point d'accès

  1. Ouvrez Administration → Serveur MCP.
  2. Cochez Activer le serveur MCP pour cette organisation.
  3. Attendez Enregistré. Si l'enregistrement échoue, la case revient à son état précédent.
  4. Sous Point d'accès, copiez l'URL affichée; elle se termine par /mcp pour l'hôte PlanRelevé courant.

La page affiche la commande de configuration de Claude Code; pour un autre client compatible, reportez le même point d'accès et le même en-tête. Exemple, avec un faux jeton :

claude mcp add --transport http planreleve https://votre-instance.example/mcp --header "Authorization: Bearer <JETON>"

N'inscrivez jamais le vrai jeton dans un dépôt, un plan, une capture d'écran, un billet de soutien, du code exécuté dans le navigateur ou l'historique d'une commande partagé.

Tant que la case est décochée, le point d'accès refuse toute connexion, même avec un jeton valide et actif. C'est une pause à l'échelle de l'organisation : elle ne convertit ni ne supprime les jetons.

Créer un jeton en lecture seule

La lecture seule est le choix sûr pour les rapports, la recherche et les essais d'intégration.

  1. Sous Jetons d'accès, entrez un Nom du jeton précis, par exemple Claude Code — portable de révision.
  2. Laissez Autoriser les outils d'écriture (jeton lecture-écriture) décoché.
  3. Cliquez Créer le jeton.
  4. Copiez immédiatement la valeur qui commence par ptk_ dans le mécanisme de secrets du client. Le message Copiez ce jeton maintenant — il ne sera plus jamais affiché. est littéral.
  5. Rechargez la page : la valeur disparaît et le tableau montre le nom, le préfixe, Lecture seule, le créateur, la date de création, Jamais sous Dernière utilisation et Actif.
  6. Configurez le client et faites un appel simple, ping ou list_projects. Rechargez ensuite la page et vérifiez que Dernière utilisation est rempli.

PlanRelevé conserve un hachage du secret et un court préfixe pour l'identifier; il ne peut pas réafficher la valeur brute. Si vous la perdez, révoquez le jeton et créez-en un autre.

Portée liée au créateur et lectures

Un jeton agit comme la personne qui l'a créé. À chaque appel, PlanRelevé vérifie de nouveau :

  1. que le jeton est actif;
  2. que son créateur est encore actif et appartient toujours à l'organisation;
  3. que l'organisation a MCP activé;
  4. que le projet appartient à la même organisation;
  5. que le créateur détient encore la permission exigée sur ce projet.

Les créateurs étant propriétaires ou administrateurs, ils ont accès à tous les projets de l'organisation; si leur rôle change, la portée future du jeton suit. Une ressource d'une autre organisation et un identifiant de projet inexistant produisent volontairement le même résultat project not found, tandis que forbidden signifie que le créateur n'a pas la permission requise sur ce projet.

Commencez par l'outil list_projects; il retourne les projets actifs que le créateur peut consulter, avec les UUID requis par les autres outils. Un jeton en lecture seule peut notamment lire les comptes confirmés (get_counts), la légende, la nomenclature, l'estimation, les pièces, les détections, les suggestions, la qualité de détection, l'état des tâches de détection et les attributs confirmés par classe (get_attributes). Les comptes viennent des données révisées : les candidats ne sont pas promus en silence, et les montants sont en dollars canadiens. Validez les quantités contre l'état courant du projet dans PlanRelevé.

get_export_links exige la permission d'export du créateur et couvre tous les téléchargements du projet — PDF d'estimation, classeur du relevé, plan annoté, PDF de câblage et tuyauterie, puis les CSV groupé, par instance et de câblage. Ces liens ramènent à l'application Web et exigent une session navigateur connectée : le jeton ne télécharge pas ces fichiers. Seuls les artefacts durables d'une révision approuvée offrent en plus un chemin /mcp/files/<id> téléchargeable avec le jeton; ils sont indisponibles tant que les Révisions sont parquées.

Ce que le serveur n'expose pas

La liste renvoyée par tools/list est délibérément plus étroite que l'assistant :

  • Les outils de soumissions fournisseurs — lister les demandes, lire un fichier reçu, importer les prix, annuler un prix — restent réservés à l'assistant. Ce sont des opérations d'organisation, et l'import passe par un plan d'actions approuvé que le modèle d'exécution immédiate de MCP ne reproduit pas.
  • La recherche Web et la lecture de page ne sont pas des outils de projet et n'apparaissent pas non plus.
  • Les outils d'une fonction désactivée pour votre organisation, ou d'une surface mise en pause, sont masqués plutôt que supprimés : tant que les Révisions sont parquées, leurs outils n'apparaissent pas dans la liste, au lieu d'être annoncés puis de répondre « non activé ». Ils réapparaissent dès que l'indicateur est réactivé.
  • Un projet archivé peut être lu et exporté, mais aucune écriture ne l'atteint — par l'application, l'assistant ou MCP.

Autoriser l'écriture seulement au besoin

Pour un jeton lecture-écriture, refaites la création en cochant Autoriser les outils d'écriture (jeton lecture-écriture) avant Créer le jeton, uniquement si le client doit modifier des données. Les outils d'écriture peuvent changer les réglages d'estimation, les lignes libres, le prix et la main-d'œuvre des trajets, la réserve, le groupe de taxes, les pièces, les assemblages, les attributs de détection, la légende, les classes, le statut des détections et le nom du projet, ainsi que lancer une détection ou une recherche de semblables, ajouter un exemple ou annuler une tâche; la liste exacte est annoncée par le serveur. Une détection lancée ainsi (run_detection, find_similar) n'est que mise en file : le calcul se fait dans le navigateur. Ouvrez d'abord le projet dans un onglet PlanRelevé et gardez-le ouvert; une tâche qu'aucun onglet ne prend en charge dans la minute échoue.

Les écritures MCP s'appliquent immédiatement. Elles ne passent pas par le plan d'actions et l'approbation du créateur utilisés par l'Assistant IA. Deux barrières demeurent : le jeton doit être lecture-écriture, puis le créateur doit avoir la permission de révision ou d'édition requise sur le projet. Un jeton en lecture seule n'annonce aucun outil d'écriture et refuse tout appel d'écriture.

Mesures recommandées :

  • un jeton distinct par appareil ou automatisation;
  • lecture seule dès qu'un rapport ou un lien d'export suffit;
  • une lecture fraîche juste avant une écriture, avec l'UUID du projet confirmé;
  • confirmation humaine dans le client avant chaque outil d'écriture, sans appel destructif sans surveillance;
  • révocation dès que l'intégration n'est plus utilisée.

Il n'existe pas de bouton pour convertir un jeton existant de lecture seule en lecture-écriture. Révoquez-le et créez un nouveau secret avec la portée voulue. Comparez cette frontière avec Assistant IA et actions approuvées et Membres, rôles et invitations.

Révoquer, désactiver et auditer

Chemin : Administration → Serveur MCP → Jetons d'accès. Le tableau affiche le nom et le préfixe, l'accès Lecture seule ou Lecture-écriture, Créé par, la date de création, la Dernière utilisation et l'état Actif ou Révoqué.

  1. Repérez le jeton par son nom, son créateur et son préfixe.
  2. Cliquez Révoquer, puis confirmez.
  3. Vérifiez que la ligne passe à Révoqué; les clients qui l'utilisent perdent l'accès immédiatement.
  4. Si toutes les intégrations doivent être coupées, décochez aussi l'activation MCP de l'organisation.

Révoquez aussi un jeton quand un appareil est perdu, qu'un flux de travail est retiré, que le jeton a pu aboutir dans des journaux ou que son créateur quitte l'organisation. Recréez un jeton plutôt que de tenter de réutiliser un jeton révoqué ou perdu.

Le Journal d'audit de l'organisation consigne l'activation et la désactivation de MCP, la création et la révocation des jetons, chaque appel d'outil d'écriture (réussi ou non), chaque appel en échec et chaque téléchargement par /mcp/files; les lectures réussies n'y figurent pas. La colonne Dernière utilisation est un indicateur sommaire, mis à jour périodiquement; ce n'est pas un journal de chaque requête ni une transcription du client. Pour une enquête, consultez ensemble Audit et données → Journal d'audit et les journaux autorisés du client, sans y enregistrer le jeton.

Dépanner une connexion

  • 401 : jeton absent, mal copié, révoqué, ou créateur désactivé. Remplacez un jeton perdu; ne le devinez pas à partir du préfixe affiché.
  • 403 au point d'accès : MCP est désactivé pour l'organisation. Vérifiez que le tableau de bord affiche Activé.
  • forbidden sur un outil : le jeton est authentifié, mais son créateur n'a pas cette permission sur le projet; corrigez l'accès plutôt que d'émettre un jeton partagé plus large.
  • project not found : relancez list_projects et utilisez l'UUID retourné; ne réutilisez pas l'identifiant d'une autre organisation.
  • Outil d'écriture absent ou erreur de lecture seule : un jeton en lecture seule ne voit pas les outils d'écriture; créez un jeton lecture-écriture dédié seulement après avoir pesé le risque d'écriture immédiate. Vérifiez aussi que le client utilise tools/list.
  • Aucun projet : confirmez que le créateur ouvre le projet actif attendu dans l'application Web et que le client vise le bon hôte PlanRelevé.
  • Détection en échec ou sans résultat : ouvrez le projet dans un onglet PlanRelevé, gardez-le ouvert, puis relancez; le calcul s'y fait.

Le point d'accès est un serveur MCP HTTP sans état : les requêtes passent par POST; il n'offre pas de flux SSE par GET ni de session à supprimer. Pour les limites de données et de confidentialité, consultez Sécurité, confidentialité et Loi 25, Administration de l'organisation et Dépannage.

Voir aussi