Intégrations API et MCP

Le serveur MCP permet à un client compatible d'interroger les projets PlanRelevé et, 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.

Prérequis et permissions

Chemin : Administration → Serveur MCP.

• Seuls les rôles d'organisation Propriétaire et Admin peuvent ouvrir la page, activer MCP et gérer les jetons.
• Le créateur du jeton doit déjà avoir accès aux projets voulus.
• Le client doit prendre en charge MCP par HTTP avec un en-tête Authorization: Bearer.

MCP est désactivé au niveau de l'organisation par défaut. Tant que Activer le serveur MCP pour cette organisation est décoché, le point d'accès refuse même un jeton valide. Le jeton MCP est accepté sur /mcp seulement; ce n'est pas une clé générale pour les routes Web ou l'API interne de l'application.

Créer un jeton en lecture seule

1. Cochez Activer le serveur MCP pour cette organisation.
2. Sous Point d'accès, copiez l'URL affichée; elle se termine par /mcp.
3. Sous Jetons d'accès, entrez un Nom du jeton précis, par exemple Claude Code — portable de révision.
4. Laissez Autoriser les outils d'écriture (jeton lecture-écriture) décoché.
5. Cliquez Créer le jeton.
6. Copiez immédiatement la valeur qui commence par ptk_. Le message Copiez ce jeton maintenant — il ne sera plus jamais affiché est littéral.
7. Rangez-la dans le mécanisme de secrets du client, puis fermez la zone d'affichage.

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.

Exemple de configuration conceptuelle, 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 ou l'historique d'une commande partagé.

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

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.

Une ressource d'une autre organisation et un identifiant de projet inexistant produisent volontairement le même résultat « projet introuvable ». Un changement de rôle réduit donc la portée future du jeton. La désactivation du créateur rend le jeton inutilisable.

Commencez par l'outil list_projects; il retourne les UUID de projet requis par les autres outils. Un jeton en lecture seule peut notamment lire les comptes confirmés, la légende, la nomenclature, l'estimation, les pièces, les suggestions, la qualité de détection et certains liens d'export. Un lien d'export peut encore demander une session Web connectée et la permission d'export.

Autoriser l'écriture seulement au besoin

Pour un nouveau jeton, cochez Autoriser les outils d'écriture (jeton lecture-écriture) uniquement si le client doit modifier des données. Ce choix ajoute des outils pouvant changer les réglages d'estimation, les lignes libres, les prix de trajets, les taxes, les pièces, les assemblages, la légende, le statut de détections ou le nom du projet.

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.

Mesures recommandées :

• un jeton distinct par appareil ou automatisation;
• lecture seule par défaut;
• un créateur dont les accès de projet sont limités à la tâche;
• confirmation humaine dans le client avant chaque outil d'écriture;
• 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.

Révoquer, désactiver et auditer

Le tableau affiche le nom, le préfixe, l'accès Lecture seule ou Lecture-écriture, le créateur, 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. 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.

Le Journal d'audit de l'organisation consigne l'activation/désactivation de MCP ainsi que la création et la révocation des jetons. La colonne Dernière utilisation est un indicateur sommaire, mis à jour périodiquement; ce n'est pas un journal détaillé de chaque requête ni une transcription du client. Pour une enquête, conservez aussi 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é. Recréez le secret si sa valeur complète n'est plus disponible.
• 403 : MCP est désactivé pour l'organisation ou la permission courante ne permet pas l'action.
• Projet introuvable : relancez list_projects et utilisez l'UUID retourné; ne réutilisez pas l'identifiant d'une autre organisation.
• Outil inconnu ou absent : un jeton lecture seule ne voit pas les outils d'écriture. Vérifiez aussi que le client utilise tools/list.
• Écriture refusée : vérifiez à la fois la portée lecture-écriture et le rôle actuel du créateur sur le projet.

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.