DataFirefly MCP Commerce: volledige gids
De MCP-server installeren, configureren en verbinden: endpoint, OAuth 2.1, Bearer-tokens, tools, scopes en bestelmodi voor PrestaShop 8 en 9.
De module DataFirefly MCP Commerce verandert uw PrestaShop-winkel in een MCP-server (Model Context Protocol) die AI-agenten, ChatGPT, Claude, Claude Desktop, Claude Code, n8n, rechtstreeks kunnen aanspreken om de catalogus te doorzoeken, winkelwagens samen te stellen en bestellingen voor te bereiden. Deze gids behandelt de installatie, het endpoint, de dubbele authenticatie (OAuth 2.1 en Bearer-tokens), het verbinden van de belangrijkste agenten, de beschikbare tools, de scopes, de bestelmodi en de probleemoplossing.
Vereisten
- PrestaShop 8.0 tot 9.x.
- PHP 7.4 tot 8.3 met de cURL-extensie actief.
- Een winkel die via HTTPS wordt geserveerd (verplicht voor de AI-connectoren).
- Aanbevolen: vriendelijke URL’s ingeschakeld (Geavanceerde instellingen > SEO & URL’s) voor schone endpoints.
De module werkt ook zonder vriendelijke URL’s: hij toont dan fallback-links op basis van index.php, zichtbaar in het tabblad Een agent verbinden van de configuratie.
Installatie
- Open in de backoffice Modules > Modulebeheer, kies Een module uploaden en upload het bestand
dfmcpcommerce.zip. - Open na de installatie de configuratie via de knop Configureren.
- De installatie maakt de technische tabellen aan (tokens, OAuth-clients, winkelwagens, logboek, rate limiter) en activeert de server standaard.
Uw MCP-endpoint
De URL van de MCP-server wordt getoond in het tabblad Een agent verbinden. Met vriendelijke URL’s ziet ze er zo uit:
https://uw-winkel.com/mcpDit is de URL die u in de connector van de agent plakt. Het transport is Streamable HTTP (JSON-RPC 2.0): één enkel endpoint, via POST.
Authenticatie: twee mechanismen
De module ondersteunt twee authenticatiemodi naast elkaar, afhankelijk van de gebruikte client.
OAuth 2.1: webconnectoren (Claude.ai, ChatGPT)
De webconnectoren van Claude.ai en ChatGPT accepteren alleen OAuth: geen geplakt token, geen token in de URL. De module levert een volledige OAuth 2.1-autorisatieserver (authorization code + PKCE S256, protected resource metadata en dynamische clientregistratie). De agent registreert zichzelf en opent een toestemmingsscherm waarop de klant zich aanmeldt en de toegang goedkeurt.
Bearer-tokens: API, Desktop, CLI, n8n
Voor de Anthropic API (MCP-connector), Claude Desktop, Claude Code of n8n maakt u een statisch Bearer-token aan in het tabblad Toegangstokens en geeft u het mee in de header Authorization: Bearer.
De tokens worden maar één keer getoond bij de aanmaak en gehasht opgeslagen (SHA-256). Kopieer het onmiddellijk; het wordt nooit meer in klare tekst getoond.
Claude.ai of ChatGPT verbinden (web)
- Houd OAuth 2.1 ingeschakeld in het tabblad Instellingen.
- Voeg in de agent een aangepaste connector toe en plak de URL van de MCP-server.
- De agent ontdekt de authenticatie automatisch, registreert zich en opent het toestemmingsscherm.
- De klant meldt zich aan bij zijn winkelaccount en keurt de gevraagde scopes goed. Er hoeft geen token te worden ingevoerd.
De Anthropic API, Claude Desktop, Claude Code of n8n verbinden
- Open het tabblad Toegangstokens, kies de scopes en klik op Een token aanmaken.
- Kopieer het getoonde token.
- Configureer de connector met de URL van de MCP-server en de header
Authorization: Bearer UW_TOKEN.
Scopes
Elke toegang wordt begrensd door scopes, aangevraagd door de agent en toegekend bij de toestemming (OAuth) of gedragen door het token (Bearer):
catalog:read: zoeken en productpagina’s, categorieën, winkelinfo, vervoerders.cart:write: aanmaken en beheren van winkelwagens.order:write: voorbereiden van bestellingen.
Beschikbare tools
Er zijn negen tools beschikbaar. Elke tool is afzonderlijk in of uit te schakelen in het tabblad Instellingen en valt onder de bijbehorende scope.
search_products: zoeken op trefwoord, referentie of EAN, met categorie- en prijsfilters.get_product: gedetailleerde productpagina (prijs, voorraad, varianten, afbeeldingen).list_categories: boomstructuur van de categorieën.get_shop_info: naam, talen, valuta’s en beleverde landen.get_carriers: beschikbare vervoerders.create_cart: aanmaken van een winkelwagen.add_to_cart: toevoegen van een product aan de winkelwagen.view_cart: inhoud en totalen van de winkelwagen.create_order: afronding, volgens de geconfigureerde bestelmodus.
Schakel de tools uit die u niet wilt blootstellen. Alleen catalog:read en zijn tools laten staan, maakt van de module bijvoorbeeld een alleen-lezen catalogusserver voor agenten.
Bestelmodi
Het tabblad Instellingen biedt twee gedragingen voor create_order.
Overdrachtsmodus (standaard)
De agent stelt de winkelwagen samen en geeft daarna een beveiligde betaal-URL terug. Door die te volgen vindt de klant exact die winkelwagen terug in zijn sessie en rondt hij de betaling af in het gebruikelijke PrestaShop-bestelproces. Er passeert geen enkel betaalgegeven via de agent: nul PCI-blootstelling.
Bestelmodus
De agent maakt rechtstreeks een bestelling aan in afwachting van betaling, in de instelbare status (standaard “Betaling per overschrijving in afwachting”). Bedoeld voor B2B, betaling bij levering of offertes.
In de bestelmodus wordt de bestelling aangemaakt zonder geïnde betaling. De afwikkeling wordt daarna geïnd volgens de methode die aan de gekozen bestelstatus is gekoppeld.
Aanvullende instellingen
- Authenticatie vereisen: aanbevolen. Een niet-geauthenticeerde request start de OAuth-flow (antwoord 401 met de header
WWW-Authenticate). - Anonieme cataloguslezing: staat
catalog:read-aanroepen zonder token toe, om een publieke catalogus bloot te stellen. - Rate limit: aantal requests per minuut en per IP (standaard 120), in een glijdend venster.
- Logging en bewaartermijn: traceert elke request (methode, tool, status, duur) in het tabblad Activiteitenlogboek, met een instelbaar aantal bewaarde regels.
Discovery en endpoints
De agenten ontdekken de server automatisch. De nuttige URL’s staan in het tabblad Een agent verbinden:
- Protected Resource Metadata (RFC 9728):
/.well-known/oauth-protected-resource. - Authorization Server Metadata (RFC 8414):
/.well-known/oauth-authorization-server. - Dynamische clientregistratie (RFC 7591), autorisatie en token: OAuth-endpoints beheerd door de module.
Ook zonder vriendelijke URL’s wijst de header WWW-Authenticate die het endpoint teruggeeft altijd naar de juiste discovery-URL op basis van index.php: de verbinding werkt in alle gevallen.
Beveiliging
- Alle tokens worden SHA-256-gehasht opgeslagen, nooit in klare tekst.
- PKCE S256 verplicht, gevalideerde
redirect_uri‘s, autorisatiecodes voor eenmalig gebruik, rotatie van de refresh tokens. - Rate limiting per IP en raadpleegbaar activiteitenlogboek.
- CORS afgehandeld voor de webconnectoren. Native compatibiliteit met multistore, meertaligheid en multi-valuta.
Probleemoplossing
- De webagent verbindt niet: controleer of de winkel op HTTPS draait en of OAuth is ingeschakeld. Plak de
/mcp-URL (geen backoffice-pagina). - De API-client geeft 401 terug: het Bearer-token ontbreekt, is ingetrokken of verlopen. Maak een nieuw aan in het tabblad Toegangstokens en controleer de header
Authorization. - Een tool verschijnt niet: hij is waarschijnlijk uitgeschakeld in de Instellingen, of de bijbehorende scope is niet toegekend.
- Fout 429: de rate limit per IP is bereikt. Verhoog indien nodig de drempel in de Instellingen.
- De overgedragen betaallink verloopt: winkelwagenlinks hebben een beperkte levensduur; vraag de agent de winkelwagen opnieuw te genereren.
De-installatie
De de-installatie verwijdert de tabellen van de module (tokens, OAuth-clients, winkelwagens, logboek, limiter) en zijn configuratievariabelen. Uw producten, klanten en bestellingen blijven onaangeroerd. Voor een simpele update volstaat het vervangen van de bestanden: het schema en de bestaande tokens blijven behouden.