# DataFirefly MCP Commerce — Vollständiger Leitfaden > Das Modul DataFirefly MCP Commerce macht aus Ihrem PrestaShop-Shop einen MCP-Server (Model Context Protocol), den KI-Agenten — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — direkt nutzen können, um den… - Seite: - Sprache: de - Aktualisiert am: 2026-06-17 - Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/serveur-mcp-commerce-agentique/index.md), [en](https://www.datafirefly.com/en/documentation/serveur-mcp-commerce-agentique/index.md), [es](https://www.datafirefly.com/es/documentation/serveur-mcp-commerce-agentique/index.md), [it](https://www.datafirefly.com/it/documentation/serveur-mcp-commerce-agentique/index.md), [pl](https://www.datafirefly.com/pl/documentation/serveur-mcp-commerce-agentique/index.md), [nl](https://www.datafirefly.com/nl/documentation/serveur-mcp-commerce-agentique/index.md), [pt](https://www.datafirefly.com/pt/documentation/serveur-mcp-commerce-agentique/index.md) - Index: Das Modul **DataFirefly MCP Commerce** macht aus Ihrem PrestaShop-Shop einen **MCP-Server** (Model Context Protocol), den KI-Agenten — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — direkt nutzen können, um den Katalog zu durchsuchen, Warenkörbe zu erstellen und Bestellungen vorzubereiten. Dieser Leitfaden behandelt Installation, Endpunkt, doppelte Authentifizierung (OAuth 2.1 und Bearer-Token), das Verbinden der wichtigsten Agenten, die bereitgestellten Tools, Scopes, Bestellmodi und Fehlerbehebung. ## Voraussetzungen - PrestaShop 8.0 bis 9.x. - PHP 7.4 bis 8.3 mit aktivierter cURL-Erweiterung. - Ein über **HTTPS** ausgelieferter Shop (für KI-Connectoren erforderlich). - Empfohlen: aktivierte **sprechende URLs** (_Erweiterte Parameter > SEO & URLs_) für saubere Endpunkte. Das Modul funktioniert auch ohne sprechende URLs: Es stellt dann `index.php`-basierte Fallback-Links bereit, die im Tab _Agent verbinden_ der Konfiguration angezeigt werden. ## Installation 1. Öffnen Sie im Backoffice _Module > Modul-Manager_, dann _Modul hochladen_ und legen Sie die Datei `dfmcpcommerce.zip` ab. 2. Öffnen Sie nach der Installation die Konfiguration über die Schaltfläche _Konfigurieren_. 3. Die Installation legt die technischen Tabellen an (Token, OAuth-Clients, Warenkörbe, Protokoll, Rate-Limiter) und aktiviert den Server standardmäßig. ## Ihr MCP-Endpunkt Die URL des MCP-Servers wird im Tab _Agent verbinden_ angezeigt. Mit sprechenden URLs sieht sie so aus: ``` https://ihr-shop.com/mcp ``` Diese URL fügen Sie in den Connector des Agenten ein. Der Transport ist **Streamable HTTP** (JSON-RPC 2.0): ein einziger Endpunkt, per POST. ## Authentifizierung: zwei Mechanismen Das Modul verwaltet je nach verwendetem Client zwei Authentifizierungsmodi parallel. ### OAuth 2.1 — Web-Connectoren (Claude.ai, ChatGPT) Die Web-Connectoren von Claude.ai und ChatGPT **akzeptieren nur OAuth**: kein eingefügtes Token, kein Token in der URL. Das Modul liefert einen vollständigen OAuth-2.1-Autorisierungsserver (authorization code + PKCE S256, Protected Resource Metadata und Dynamic Client Registration). Der Agent registriert sich selbst und öffnet einen Zustimmungsbildschirm, auf dem sich der Kunde anmeldet und den Zugriff genehmigt. ### Bearer-Token — API, Desktop, CLI, n8n Für die Anthropic API (MCP-Connector), Claude Desktop, Claude Code oder n8n erstellen Sie ein **statisches Bearer-Token** im Tab _Zugriffstoken_ und übergeben es im Header `Authorization: Bearer`. Token werden **nur einmal** bei der Erstellung angezeigt und gehasht gespeichert (SHA-256). Kopieren Sie es sofort; es wird nie wieder im Klartext angezeigt. ## Claude.ai oder ChatGPT verbinden (Web) 1. Lassen Sie **OAuth 2.1** im Tab _Einstellungen_ aktiviert. 2. Fügen Sie im Agenten einen benutzerdefinierten Connector hinzu und fügen Sie die MCP-Server-URL ein. 3. Der Agent erkennt die Authentifizierung automatisch, registriert sich und öffnet den Zustimmungsbildschirm. 4. Der Kunde meldet sich bei seinem Shop-Konto an und genehmigt die angeforderten Scopes. Kein Token einzugeben. ## Anthropic API, Claude Desktop, Claude Code oder n8n verbinden 1. Öffnen Sie den Tab _Zugriffstoken_, wählen Sie die Scopes und klicken Sie auf **Token erstellen**. 2. Kopieren Sie das angezeigte Token. 3. Konfigurieren Sie den Connector mit der MCP-Server-URL und dem Header `Authorization: Bearer IHR_TOKEN`. ## Scopes Jeder Zugriff ist durch Scopes begrenzt, die vom Agenten angefordert und bei der Zustimmung gewährt (OAuth) oder vom Token getragen werden (Bearer): - `catalog:read` — Produktsuche und -details, Kategorien, Shop-Infos, Versanddienstleister. - `cart:write` — Erstellung und Verwaltung von Warenkörben. - `order:write` — Bestellvorbereitung. ## Bereitgestellte Tools Neun Tools stehen zur Verfügung. Jedes lässt sich im Tab _Einstellungen_ einzeln aktivieren oder deaktivieren und unterliegt dem passenden Scope. - `search_products` — Suche nach Stichwort, Referenz oder EAN, mit Kategorie- und Preisfiltern. - `get_product` — detaillierte Produktseite (Preis, Bestand, Varianten, Bilder). - `list_categories` — Kategoriebaum. - `get_shop_info` — Name, Sprachen, Währungen und Versandländer. - `get_carriers` — verfügbare Versanddienstleister. - `create_cart` — Erstellung eines Warenkorbs. - `add_to_cart` — ein Produkt zum Warenkorb hinzufügen. - `view_cart` — Inhalt und Summen des Warenkorbs. - `create_order` — Abschluss, je nach konfiguriertem Bestellmodus. Deaktivieren Sie die Tools, die Sie nicht bereitstellen möchten. Wenn Sie etwa nur `catalog:read` und seine Tools belassen, wird das Modul zu einem schreibgeschützten Katalogserver für Agenten. ## Bestellmodi Der Tab _Einstellungen_ bietet zwei Verhaltensweisen für `create_order`. ### Übergabemodus (Standard) Der Agent stellt den Warenkorb zusammen und gibt eine **sichere Checkout-URL** zurück. Folgt der Kunde ihr, findet er genau diesen Warenkorb in seiner Sitzung und schließt die Zahlung im gewohnten PrestaShop-Ablauf ab. Keine Zahlungsdaten fließen durch den Agenten: **null PCI-Exposition**. ### Bestellmodus Der Agent erstellt direkt eine Bestellung mit Status **Zahlung ausstehend**, im konfigurierbaren Status (standardmäßig „Zahlung per Banküberweisung ausstehend"). Gedacht für B2B, Nachnahme oder Angebote. Im Bestellmodus wird die Bestellung ohne eingezogene Zahlung erstellt. Die Zahlung wird anschließend gemäß der dem gewählten Bestellstatus zugeordneten Methode eingezogen. ## Weitere Einstellungen - **Authentifizierung erfordern**: empfohlen. Eine nicht authentifizierte Anfrage löst den OAuth-Ablauf aus (401-Antwort mit `WWW-Authenticate`-Header). - **Anonymes Lesen des Katalogs**: erlaubt `catalog:read`-Aufrufe ohne Token, um einen öffentlichen Katalog bereitzustellen. - **Rate-Limit**: Anzahl der Anfragen pro Minute und IP (Standard 120), gleitendes Fenster. - **Protokollierung** und **Aufbewahrung**: zeichnet jede Anfrage (Methode, Tool, Status, Dauer) im Tab _Aktivitätsprotokoll_ auf, mit konfigurierbarer Anzahl aufbewahrter Zeilen. ## Erkennung und Endpunkte Agenten erkennen den Server automatisch. Die nützlichen URLs sind im Tab _Agent verbinden_ aufgeführt: - **Protected Resource Metadata** (RFC 9728) — `/.well-known/oauth-protected-resource`. - **Authorization Server Metadata** (RFC 8414) — `/.well-known/oauth-authorization-server`. - **Dynamic Client Registration** (RFC 7591), **Autorisierung** und **Token**: vom Modul verwaltete OAuth-Endpunkte. Auch ohne sprechende URLs verweist der vom Endpunkt zurückgegebene `WWW-Authenticate`-Header stets auf die korrekte `index.php`-basierte Erkennungs-URL: Die Verbindung funktioniert in allen Fällen. ## Sicherheit - Alle Token werden **mit SHA-256 gehasht** gespeichert, niemals im Klartext. - PKCE S256 obligatorisch, `redirect_uri` validiert, einmalig verwendbare Autorisierungscodes, Rotation der Refresh-Token. - Rate-Limiting pro IP und einsehbares Aktivitätsprotokoll. - CORS für Web-Connectoren verwaltet. Native Multishop-, Mehrsprachen- und Mehrwährungskompatibilität. ## Fehlerbehebung - **Der Web-Agent verbindet sich nicht**: Prüfen Sie, ob der Shop über HTTPS läuft und OAuth aktiviert ist. Fügen Sie die URL `/mcp` ein (keine Backoffice-Seite). - **Der API-Client gibt 401 zurück**: Das Bearer-Token fehlt, ist widerrufen oder abgelaufen. Erstellen Sie ein neues im Tab _Zugriffstoken_ und prüfen Sie den `Authorization`-Header. - **Ein Tool erscheint nicht**: Es ist wahrscheinlich in den _Einstellungen_ deaktiviert, oder der passende Scope wurde nicht gewährt. - **Fehler 429**: Das Rate-Limit pro IP ist erreicht. Erhöhen Sie bei Bedarf den Schwellenwert in den _Einstellungen_. - **Der übergebene Checkout-Link läuft ab**: Warenkorb-Links haben eine begrenzte Lebensdauer; bitten Sie den Agenten, den Warenkorb neu zu erstellen. ## Deinstallation Die Deinstallation entfernt die Tabellen des Moduls (Token, OAuth-Clients, Warenkörbe, Protokoll, Rate-Limiter) und seine Konfigurationsvariablen. Ihre Produkte, Kunden und Bestellungen sind nicht betroffen. Für ein einfaches Update genügt das Ersetzen der Dateien: Schema und vorhandene Token bleiben erhalten.