PS PrestaShop PrestaShop Intermédiaire

DataFirefly MCP Commerce — Guide complet

Installer, configurer et connecter le serveur MCP : endpoint, OAuth 2.1, jetons Bearer, outils, scopes et modes de commande pour PrestaShop 8 et 9.

Mis à jour Version du module 1.0.0

Le module DataFirefly MCP Commerce transforme votre boutique PrestaShop en serveur MCP (Model Context Protocol) que les agents IA — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — peuvent consommer directement pour parcourir le catalogue, constituer des paniers et préparer des commandes. Ce guide couvre l’installation, l’endpoint, la double authentification (OAuth 2.1 et jetons Bearer), la connexion des principaux agents, les outils exposés, les scopes, les modes de commande et le dépannage.

Prérequis

  • PrestaShop 8.0 à 9.x.
  • PHP 7.4 à 8.3 avec l’extension cURL active.
  • Une boutique servie en HTTPS (obligatoire pour les connecteurs IA).
  • Recommandé : les URL simplifiées activées (Paramètres avancés > SEO & URL) pour des points de terminaison propres.

Le module fonctionne aussi sans URL simplifiées : il expose alors des liens de repli basés sur index.php, affichés dans l’onglet Connecter un agent de la configuration.

Installation

  1. Dans le back-office, ouvrez Modules > Module Manager puis Téléverser un module et déposez le fichier dfmcpcommerce.zip.
  2. Une fois installé, ouvrez la configuration via le bouton Configurer.
  3. L’installation crée les tables techniques (jetons, clients OAuth, paniers, journal, limiteur de débit) et active le serveur par défaut.

Votre endpoint MCP

L’URL du serveur MCP est affichée dans l’onglet Connecter un agent. Avec les URL simplifiées, elle ressemble à :

https://votre-boutique.com/mcp

C’est cette URL que vous collez dans le connecteur de l’agent. Le transport est Streamable HTTP (JSON-RPC 2.0) : un endpoint unique, en POST.

Authentification : deux mécanismes

Le module gère deux modes d’authentification en parallèle, selon le client utilisé.

OAuth 2.1 — connecteurs web (Claude.ai, ChatGPT)

Les connecteurs web de Claude.ai et de ChatGPT n’acceptent qu’OAuth : pas de jeton collé, pas de jeton dans l’URL. Le module fournit un serveur d’autorisation OAuth 2.1 complet (authorization code + PKCE S256, métadonnées de ressource protégée et enregistrement dynamique de client). L’agent se déclare seul et ouvre un écran de consentement où le client se connecte et approuve l’accès.

Jetons Bearer — API, Desktop, CLI, n8n

Pour l’API Anthropic (connecteur MCP), Claude Desktop, Claude Code ou n8n, vous créez un jeton Bearer statique dans l’onglet Jetons d’accès et le passez dans l’en-tête Authorization: Bearer.

Les jetons sont affichés une seule fois à la création et stockés hachés (SHA-256). Copiez-le immédiatement ; il ne sera plus jamais affiché en clair.

Connecter Claude.ai ou ChatGPT (web)

  1. Gardez OAuth 2.1 activé dans l’onglet Réglages.
  2. Dans l’agent, ajoutez un connecteur personnalisé et collez l’URL du serveur MCP.
  3. L’agent découvre automatiquement l’authentification, s’enregistre et ouvre l’écran de consentement.
  4. Le client se connecte à son compte boutique et approuve les scopes demandés. Aucun jeton à saisir.

Connecter l’API Anthropic, Claude Desktop, Claude Code ou n8n

  1. Ouvrez l’onglet Jetons d’accès, choisissez les scopes et cliquez sur Créer un jeton.
  2. Copiez le jeton affiché.
  3. Configurez le connecteur avec l’URL du serveur MCP et l’en-tête Authorization: Bearer VOTRE_JETON.

Scopes

Chaque accès est borné par des scopes, demandés par l’agent et accordés au consentement (OAuth) ou portés par le jeton (Bearer) :

  • catalog:read — recherche et fiches produits, catégories, infos boutique, transporteurs.
  • cart:write — création et gestion de paniers.
  • order:write — préparation de commande.

Outils exposés

Neuf outils sont disponibles. Chacun est activable ou désactivable individuellement dans l’onglet Réglages, et soumis au scope correspondant.

  • search_products — recherche par mot-clé, référence ou EAN, avec filtres catégorie et prix.
  • get_product — fiche détaillée d’un produit (prix, stock, déclinaisons, images).
  • list_categories — arborescence des catégories.
  • get_shop_info — nom, langues, devises et pays livrés.
  • get_carriers — transporteurs disponibles.
  • create_cart — création d’un panier.
  • add_to_cart — ajout d’un produit au panier.
  • view_cart — contenu et totaux du panier.
  • create_order — finalisation, selon le mode de commande configuré.

Désactivez les outils que vous ne souhaitez pas exposer. Par exemple, ne laisser que catalog:read et ses outils transforme le module en serveur de catalogue en lecture seule pour les agents.

Modes de commande

L’onglet Réglages propose deux comportements pour create_order.

Mode transfert (par défaut)

L’agent assemble le panier puis renvoie une URL de paiement sécurisée. En la suivant, le client retrouve exactement ce panier dans sa session et finalise le paiement sur le tunnel PrestaShop habituel. Aucune donnée de paiement ne transite par l’agent : zéro exposition PCI.

Mode commande

L’agent crée directement une commande en attente de paiement, dans l’état configurable (par défaut « Virement bancaire en attente »). Pensé pour le B2B, le paiement à la livraison ou les devis.

En mode commande, la commande est créée sans paiement encaissé. Le règlement est ensuite collecté selon la méthode associée à l’état de commande choisi.

Réglages complémentaires

  • Exiger l’authentification : recommandé. Une requête non authentifiée déclenche le flux OAuth (réponse 401 avec en-tête WWW-Authenticate).
  • Lecture anonyme du catalogue : autorise les appels catalog:read sans jeton, pour exposer un catalogue public.
  • Limite de débit : nombre de requêtes par minute et par IP (par défaut 120), en fenêtre glissante.
  • Journalisation et rétention : trace chaque requête (méthode, outil, statut, durée) dans l’onglet Journal d’activité, avec un nombre de lignes conservées configurable.

Découverte et points de terminaison

Les agents découvrent le serveur automatiquement. Les URL utiles sont listées dans l’onglet Connecter un agent :

  • Protected Resource Metadata (RFC 9728) — /.well-known/oauth-protected-resource.
  • Authorization Server Metadata (RFC 8414) — /.well-known/oauth-authorization-server.
  • Enregistrement dynamique de client (RFC 7591), autorisation et jeton : endpoints OAuth gérés par le module.

Même sans URL simplifiées, l’en-tête WWW-Authenticate renvoyé par l’endpoint pointe toujours vers la bonne URL de découverte basée sur index.php : la connexion fonctionne dans tous les cas.

Sécurité

  • Tous les jetons sont stockés hachés en SHA-256, jamais en clair.
  • PKCE S256 obligatoire, redirect_uri validées, codes d’autorisation à usage unique, rotation des refresh tokens.
  • Limitation de débit par IP et journal d’activité consultable.
  • CORS géré pour les connecteurs web. Compatibilité multiboutique, multilingue et multidevise native.

Dépannage

  • L’agent web ne se connecte pas : vérifiez que la boutique est en HTTPS et qu’OAuth est activé. Collez bien l’URL /mcp (pas une page du back-office).
  • Le client API renvoie 401 : le jeton Bearer est absent, révoqué ou expiré. Recréez-en un dans l’onglet Jetons d’accès et vérifiez l’en-tête Authorization.
  • Un outil n’apparaît pas : il est probablement désactivé dans les Réglages, ou le scope correspondant n’a pas été accordé.
  • Erreur 429 : la limite de débit par IP est atteinte. Augmentez le seuil dans les Réglages si nécessaire.
  • Le lien de paiement transféré expire : les liens de panier ont une durée de vie limitée ; demandez à l’agent de régénérer le panier.

Désinstallation

La désinstallation supprime les tables du module (jetons, clients OAuth, paniers, journal, limiteur) et ses variables de configuration. Vos produits, clients et commandes ne sont pas affectés. Pour une simple mise à jour, remplacer les fichiers suffit : le schéma et les jetons existants sont préservés.

Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support