DataFirefly MCP Commerce — Complete guide

The DataFirefly MCP Commerce module turns your PrestaShop store into an MCP server (Model Context Protocol) that AI agents — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — can consume directly to browse the catalogue, build carts and prepare orders. This guide covers installation, the endpoint, dual authentication (OAuth 2.1 and Bearer tokens), connecting the main agents, the exposed tools, scopes, order modes and troubleshooting.

Requirements

• PrestaShop 8.0 to 9.x.
• PHP 7.4 to 8.3 with the cURL extension enabled.
• A store served over HTTPS (required by AI connectors).
• Recommended: friendly URLs enabled (Advanced Parameters > SEO & URLs) for clean endpoints.

Installation

1. In the back office, open Modules > Module Manager, then Upload a module and drop the dfmcpcommerce.zip file.
2. Once installed, open the configuration via the Configure button.
3. Installation creates the technical tables (tokens, OAuth clients, carts, log, rate limiter) and enables the server by default.

Your MCP endpoint

The MCP server URL is shown in the Connect an agent tab. With friendly URLs, it looks like:

https://your-store.com/mcp

This is the URL you paste into the agent connector. The transport is Streamable HTTP (JSON-RPC 2.0): a single endpoint, over POST.

Authentication: two mechanisms

The module handles two authentication modes in parallel, depending on the client used.

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

The Claude.ai and ChatGPT web connectors only accept OAuth: no pasted token, no token in the URL. The module ships a full OAuth 2.1 authorization server (authorization code + PKCE S256, Protected Resource Metadata and Dynamic Client Registration). The agent registers itself and opens a consent screen where the shopper logs in and approves access.

Bearer tokens — API, Desktop, CLI, n8n

For the Anthropic API (MCP connector), Claude Desktop, Claude Code or n8n, you create a static Bearer token in the Access tokens tab and pass it in the Authorization: Bearer header.

Connect Claude.ai or ChatGPT (web)

1. Keep OAuth 2.1 enabled in the Settings tab.
2. In the agent, add a custom connector and paste the MCP server URL.
3. The agent auto-discovers authentication, registers itself and opens the consent screen.
4. The shopper logs in to their store account and approves the requested scopes. No token to enter.

Connect the Anthropic API, Claude Desktop, Claude Code or n8n

1. Open the Access tokens tab, choose the scopes and click Create token.
2. Copy the displayed token.
3. Configure the connector with the MCP server URL and the Authorization: Bearer YOUR_TOKEN header.

Scopes

Every access is bounded by scopes, requested by the agent and granted at consent (OAuth) or carried by the token (Bearer):

• catalog:read — product search and details, categories, shop info, carriers.
• cart:write — cart creation and management.
• order:write — order preparation.

Exposed tools

Nine tools are available. Each can be enabled or disabled individually in the Settings tab, and is subject to the matching scope.

• search_products — search by keyword, reference or EAN, with category and price filters.
• get_product — detailed product page (price, stock, variants, images).
• list_categories — category tree.
• get_shop_info — name, languages, currencies and shipping countries.
• get_carriers — available carriers.
• create_cart — cart creation.
• add_to_cart — add a product to the cart.
• view_cart — cart contents and totals.
• create_order — finalization, depending on the configured order mode.

Order modes

The Settings tab offers two behaviours for create_order.

Handoff mode (default)

The agent assembles the cart then returns a secure checkout URL. Following it, the shopper finds that exact cart in their session and completes payment on the usual PrestaShop flow. No payment data flows through the agent: zero PCI exposure.

Order mode

The agent directly creates an awaiting-payment order, in the configurable state (default “Awaiting bank wire payment”). Designed for B2B, cash on delivery or quotes.

Additional settings

• Require authentication: recommended. An unauthenticated request triggers the OAuth flow (401 response with a WWW-Authenticate header).
• Anonymous catalogue reads: allow catalog:read calls without a token, to expose a public catalogue.
• Rate limit: number of requests per minute per IP (default 120), sliding window.
• Logging and retention: traces every request (method, tool, status, duration) in the Activity log tab, with a configurable number of retained rows.

Discovery and endpoints

Agents discover the server automatically. The useful URLs are listed in the Connect an agent tab:

• 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), authorization and token: OAuth endpoints handled by the module.

Security

• All tokens are stored hashed with SHA-256, never in clear text.
• PKCE S256 mandatory, redirect_uri validated, single-use authorization codes, refresh token rotation.
• Per-IP rate limiting and a consultable activity log.
• CORS handled for web connectors. Native multistore, multilingual and multicurrency compatibility.

Troubleshooting

• The web agent won’t connect: check that the store is on HTTPS and that OAuth is enabled. Make sure you paste the /mcp URL (not a back-office page).
• The API client returns 401: the Bearer token is missing, revoked or expired. Create a new one in the Access tokens tab and check the Authorization header.
• A tool doesn’t appear: it is probably disabled in Settings, or the matching scope was not granted.
• 429 error: the per-IP rate limit is reached. Raise the threshold in Settings if needed.
• The handed-off checkout link expires: cart links have a limited lifetime; ask the agent to regenerate the cart.

Uninstallation

Uninstalling removes the module’s tables (tokens, OAuth clients, carts, log, rate limiter) and its configuration variables. Your products, customers and orders are not affected. For a simple update, replacing the files is enough: the schema and existing tokens are preserved.