View Categories

Le serveur MCP

3 minutes

Introduction #

Le serveur MCP (Model Context Protocol) de Kafinea permet aux clients IA externes (Claude Desktop, Cursor, Windsurf, VS Code, JetBrains…) de se connecter à l’instance ERP pour interroger les données via un protocole standardisé.

Cette page décrit l’architecture technique, la sécurité et la configuration du serveur MCP pour les administrateurs.

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 Paramètres d’activation et de limitation du serveur

2. Authentification #

L’authentification se fait via le header HTTP X-Kafinea-Credentials au format :

X-Kafinea-Credentials: username:accesskey
  • Le username est le nom d’utilisateur Kafinea
  • L’accesskey est la clé d’accès de l’utilisateur (visible dans Mes Préférences)

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

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
  • Protection contre les injections

Recommandations #

  • Déployez le serveur MCP uniquement sur des connexions HTTPS
  • Ne publiez jamais les identifiants dans un dépôt public
  • Surveillez les logs d’accès pour détecter les usages anormaux
  • Utilisez des clés d’accès dédiées pour les intégrations MCP si possible

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 #

La configuration du serveur MCP est gérée par l’administrateur serveur. Les paramètres incluent :

  • Activation/désactivation du serveur
  • Liste des modules exposés
  • Limites de requêtes

Note : Contactez votre administrateur serveur si vous souhaitez modifier la liste des modules exposés ou les limites de requêtes.

7. Activation #

Le serveur MCP est activé via les feature flags de Kafinea. Pour l’activer :

  1. Vérifiez que le feature flag MCP est activé dans la configuration
  2. Assurez-vous que le endpoint mcp/index.php est accessible depuis l’extérieur (ou depuis le réseau des utilisateurs)
  3. Informez les utilisateurs qu’ils peuvent récupérer leur configuration depuis Mes Préférences > Configuration MCP

8. Diagnostic #

En cas de problème de connexion :

  1. Vérifiez que le endpoint MCP est accessible depuis le poste de l’utilisateur
  2. Vérifiez les identifiants utilisateur (username + accesskey valides)
  3. Vérifiez que le feature flag MCP est bien activé

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’administrateur serveur peut également restreindre la liste des modules exposés au niveau de la configuration du serveur.

Références associées #