# 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…
- Page:
- Language: en
- Last updated: 2026-06-17
- Other languages: [fr](https://www.datafirefly.com/documentation/serveur-mcp-commerce-agentique/index.md), [es](https://www.datafirefly.com/es/documentation/serveur-mcp-commerce-agentique/index.md), [de](https://www.datafirefly.com/de/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:
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.
The module also works without friendly URLs: it then exposes `index.php`-based fallback links, shown in the _Connect an agent_ tab of the configuration.
## 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.
Tokens are shown **only once** at creation and stored hashed (SHA-256). Copy it immediately; it will never be shown in clear text again.
## 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.
Disable the tools you do not want to expose. For example, keeping only `catalog:read` and its tools turns the module into a read-only catalogue server for agents.
## 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.
In order mode, the order is created without collected payment. Payment is then collected according to the method associated with the chosen order state.
## 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.
Even without friendly URLs, the `WWW-Authenticate` header returned by the endpoint always points to the correct `index.php`-based discovery URL: the connection works in all cases.
## 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.