View Categories

Administrer le serveur MCP

8 minutes

0:00 8:40

Introduction #

Le serveur MCP (Model Context Protocol) de Kafinea permet aux assistants IA (ChatGPT, Claude, Gemini, Copilot, Cursor…) de se connecter à l’ERP pour interroger les données via un protocole standardisé.

Cette page décrit l’architecture technique, la sécurité, l’activation et le diagnostic du serveur MCP pour les administrateurs. Pour connecter votre propre assistant, consultez Connecter ChatGPT, Claude ou Gemini à Kafinea.

1. Architecture #

Le serveur MCP de Kafinea est composé de plusieurs briques :

Composant Rôle
Point d’entrée HTTP Réception des requêtes MCP (protocole Streamable HTTP)
Outils (Tools) Fonctions exposées aux clients IA (recherche, lecture, navigation)
Ressources (Resources) Données de contexte consultables par le client IA
Authentification Validation des identifiants utilisateur à chaque requête
Sécurité Application des droits d’accès et des contrôles de sécurité
Configuration Activation de la connexion avec le compte Kafinea pour l’installation

2. Authentification #

Le serveur MCP accepte deux modes de connexion, sur la même adresse : l’adresse de l’installation suivie de /mcp/index.php, par exemple https://apps.kafinea.com/<installation>/mcp/index.php. Dans les deux cas, l’utilisateur doit disposer d’un compte actif sur l’installation.

Connexion avec le compte Kafinea (recommandée) #

L’utilisateur ajoute l’adresse de connexion dans son assistant IA, se connecte avec son compte Kafinea habituel, puis autorise l’accès demandé. Aucune clé n’est enregistrée dans l’assistant.

Deux adresses sont proposées :

  • L’adresse unique https://mcp.kafinea.com/mcp (recommandée) : une seule connexion donne accès à toutes les installations sur lesquelles l’utilisateur a été invité. La liste suit ses invitations : une installation ouverte plus tard est accessible sans nouvelle configuration, un accès retiré l’est en quelques minutes. Chaque opération désigne explicitement son installation et s’exécute avec le compte et les droits de l’utilisateur dans celle-ci. C’est l’adresse à privilégier pour un intégrateur qui suit plusieurs clients, ou pour une organisation qui partage un même connecteur entre ses membres.
  • L’adresse de l’installation : la connexion est limitée à cette installation.

Les droits accordés à l’assistant (lecture, écriture, configuration) sont affichés lors de l’autorisation. L’utilisateur retrouve ses assistants autorisés dans le menu utilisateur, Connecter mon assistant IA, section Vos assistants connectés, où il peut les révoquer à tout moment. Après une révocation, les accès déjà délivrés expirent en quelques minutes.

Ce mode est actif sur les installations hébergées par Kafinea (voir Activation).

Connexion avec une clé d’accès #

Ce mode sert aux assistants configurés avec des identifiants fixes. Chaque requête transmet le nom d’utilisateur et la clé d’accès personnelle, dans l’un des formats suivants :

X-Kafinea-Credentials: username:accesskey
Authorization: Basic base64(username:accesskey)
Authorization: Bearer username:accesskey
X-Kafinea-Username: username
X-Kafinea-AccessKey: accesskey
  • Le username est le nom d’utilisateur Kafinea
  • L’accesskey est la clé d’accès de l’utilisateur, propre à chaque installation (visible dans le menu utilisateur, Connecter mon assistant IA, section Intégration technique (clé d’accès), après Afficher la clé)

Le serveur valide les identifiants et établit le contexte utilisateur pour la requête.

Un utilisateur régénère sa clé depuis Mes préférences, menu Plus, Modifier la clé d’accès. La nouvelle clé remplace l’ancienne immédiatement, pour tous les outils qui l’utilisent : mettez à jour chaque assistant configuré avec cette clé.

3. Sécurité #

Droits d’accès #

Chaque requête MCP est exécutée dans le contexte de l’utilisateur authentifié. Les droits d’accès aux modules, enregistrements et champs sont respectés.

Contrôles de sécurité supplémentaires #

En plus des droits d’accès utilisateur, le serveur MCP applique des contrôles supplémentaires :

  • Validation des paramètres d’entrée
  • Filtrage des modules et champs sensibles : les clés d’accès des utilisateurs ne sont jamais transmises par le serveur MCP, y compris à un administrateur
  • Protection contre les injections

Recommandations #

  • Déployez le serveur MCP uniquement sur des connexions HTTPS
  • Préférez la connexion avec le compte Kafinea : aucune clé n’est stockée dans l’assistant et chaque application autorisée se révoque individuellement
  • Ne publiez jamais les identifiants dans un dépôt public
  • Surveillez les logs d’accès pour détecter les usages anormaux

4. Outils exposés (Tools) #

Les outils exposés par le serveur MCP permettent aux clients IA de :

  • Rechercher des enregistrements dans les modules Kafinea
  • Lire le détail d’un enregistrement spécifique
  • Naviguer les relations entre enregistrements
  • Lister les modules et champs disponibles
  • Parcourir et compléter les listes connexes déclarées sur une fiche
  • Manipuler les liens qualifiés avec les outils génériques de création, lecture, modification et suppression
  • Gérer les produits génériques et spécifiques avec les outils génériques sur les Produits et leur liste connexe
  • Lire et modifier la composition des kits avec les outils dédiés product_kit_get_components, product_kit_set_components, product_kit_add_component et product_kit_remove_component

Chaque outil respecte les droits d’accès de l’utilisateur connecté.

La ressource kafinea://relationship-concepts explique aux clients IA comment choisir entre une liste connexe, un lien qualifié, un rattachement générique/spécifique et une composition de kit. Elle précise aussi que les champs nécessaires doivent être visibles dans l’agencement et que les prix sont recalculés automatiquement.

Elle décrit également la lecture détaillée des bons de réduction répartis sur les lignes d’un devis, d’un bon de commande ou d’une facture directement importé d’une boutique. L’outil get_record peut renvoyer une propriété facultative en lecture seule : chaque part de bon se rapproche de sa ligne par lineItemId. Les montants décrivent l’import et isCurrent indique si la remise actuelle correspond encore aux composantes enregistrées. Cette propriété n’apparaît pas dans les listes et ne se modifie pas avec les outils d’écriture.

5. Ressources exposées (Resources) #

Les ressources exposent des données de contexte que le client IA peut consulter :

  • Informations sur l’instance Kafinea
  • Structure des modules disponibles
  • Métadonnées des champs
  • Guide de choix entre listes connexes, liens qualifiés et kits de produits

6. Configuration #

  • Données accessibles : l’assistant accède exactement à ce que l’utilisateur voit dans Kafinea. Pour restreindre ce qu’un utilisateur peut consulter ou modifier via MCP, ajustez ses droits (profil, rôle, règles de partage) : les mêmes règles s’appliquent à l’écran, à l’API et au serveur MCP.
  • Connexion avec le compte Kafinea : active sur les installations hébergées par Kafinea ; sur une autre installation, elle s’active dans la configuration du serveur, par l’équipe qui l’héberge.
  • Connexion avec une clé d’accès : elle ne demande aucun réglage.

7. Activation #

Connexion avec une clé d’accès #

Ce mode est disponible sur toute installation, sans activation. Chaque utilisateur actif retrouve une configuration prête à copier, avec l’adresse du point d’accès, son nom d’utilisateur et sa clé, dans le menu utilisateur, Connecter mon assistant IA, section Intégration technique (clé d’accès).

Connexion avec le compte Kafinea #

Ce mode est actif sur les installations hébergées par Kafinea, ainsi que l’adresse unique : la page Connecter mon assistant IA affiche alors les étapes par assistant et l’adresse de connexion ; l’adresse propre à l’installation se trouve sous Limiter l’assistant à cet espace.

Sur une installation hébergée ailleurs, il s’active une fois, dans la configuration du serveur et non dans les paramètres de Kafinea. Si vous n’avez pas accès au serveur, adressez la demande à votre intégrateur ou à votre hébergeur. Les étapes sont rappelées aux administrateurs sur la page Connecter mon assistant IA :

  1. Faire déployer et configurer le service d’authentification des assistants IA pour l’installation
  2. Faire renseigner l’adresse sécurisée de l’installation et activer la connexion avec les comptes Kafinea
  3. Recharger la page Connecter mon assistant IA : les étapes de connexion et l’adresse apparaissent. Faites ensuite un essai depuis un assistant

Tant que ce mode n’est pas activé, la page l’indique et propose le bouton Copier la demande d’activation, que l’utilisateur transmet à l’équipe qui gère l’installation.

Pour se connecter avec ce mode, l’utilisateur doit avoir été invité sur l’installation et disposer d’un compte actif.

Dans les deux modes, le point d’accès mcp/index.php doit être joignable depuis le poste de l’utilisateur, ou depuis Internet lorsque l’assistant IA fonctionne en ligne.

8. Diagnostic #

En cas de problème de connexion :

  1. Vérifiez que le point d’accès est joignable depuis le poste de l’utilisateur, ou depuis Internet pour un assistant en ligne
  2. Clé d’accès : comparez la configuration de l’outil avec celle de la section Intégration technique (clé d’accès) de la page Connecter mon assistant IA. Après une régénération de la clé, mettez à jour l’outil
  3. Compte Kafinea : la page Connecter mon assistant IA affiche l’adresse de connexion lorsque le service est configuré. Vérifiez aussi que l’utilisateur a été invité sur l’installation
  4. Vérifiez que le compte de l’utilisateur est actif : un compte désactivé ne peut plus se connecter, quel que soit le mode

FAQ #

Le serveur MCP est-il compatible avec tous les clients IA ?
Le serveur implémente le protocole MCP standard (Streamable HTTP). Tout client compatible MCP peut s’y connecter.

Puis-je limiter les modules accessibles via MCP ?
Oui, via les droits d’accès des profils utilisateurs dans Kafinea : l’assistant n’accède qu’aux modules, enregistrements et champs que l’utilisateur voit.

Références associées #