DataFirefly MCP Commerce — Guida completa
Installare, configurare e collegare il server MCP: endpoint, OAuth 2.1, token Bearer, strumenti, scope e modalità d'ordine per PrestaShop 8 e 9.
Il modulo DataFirefly MCP Commerce trasforma il tuo negozio PrestaShop in un server MCP (Model Context Protocol) che gli agenti IA — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — possono usare direttamente per esplorare il catalogo, comporre carrelli e preparare ordini. Questa guida copre l’installazione, l’endpoint, la doppia autenticazione (OAuth 2.1 e token Bearer), la connessione dei principali agenti, gli strumenti esposti, gli scope, le modalità d’ordine e la risoluzione dei problemi.
Requisiti
- PrestaShop 8.0 fino a 9.x.
- PHP 7.4 fino a 8.3 con l’estensione cURL attiva.
- Un negozio servito in HTTPS (obbligatorio per i connettori IA).
- Consigliato: gli URL semplificati attivati (Parametri avanzati > SEO & URL) per endpoint puliti.
Il modulo funziona anche senza URL semplificati: espone allora link di ripiego basati su index.php, mostrati nella scheda Collega un agente della configurazione.
Installazione
- Nel back office, apri Moduli > Gestore moduli, poi Carica un modulo e rilascia il file
dfmcpcommerce.zip. - Una volta installato, apri la configurazione tramite il pulsante Configura.
- L’installazione crea le tabelle tecniche (token, client OAuth, carrelli, registro, limitatore di frequenza) e attiva il server per impostazione predefinita.
Il tuo endpoint MCP
L’URL del server MCP è mostrato nella scheda Collega un agente. Con gli URL semplificati, assomiglia a:
https://il-tuo-negozio.com/mcpÈ questo l’URL che incolli nel connettore dell’agente. Il trasporto è Streamable HTTP (JSON-RPC 2.0): un unico endpoint, in POST.
Autenticazione: due meccanismi
Il modulo gestisce due modalità di autenticazione in parallelo, a seconda del client usato.
OAuth 2.1 — connettori web (Claude.ai, ChatGPT)
I connettori web di Claude.ai e ChatGPT accettano solo OAuth: nessun token incollato, nessun token nell’URL. Il modulo include un server di autorizzazione OAuth 2.1 completo (authorization code + PKCE S256, metadati di risorsa protetta e registrazione dinamica del client). L’agente si registra da solo e apre una schermata di consenso in cui il cliente accede e approva l’accesso.
Token Bearer — API, Desktop, CLI, n8n
Per l’API Anthropic (connettore MCP), Claude Desktop, Claude Code o n8n, crei un token Bearer statico nella scheda Token di accesso e lo passi nell’header Authorization: Bearer.
I token vengono mostrati una sola volta alla creazione e memorizzati con hash (SHA-256). Copialo subito; non sarà più mostrato in chiaro.
Collegare Claude.ai o ChatGPT (web)
- Mantieni OAuth 2.1 attivo nella scheda Impostazioni.
- Nell’agente, aggiungi un connettore personalizzato e incolla l’URL del server MCP.
- L’agente scopre automaticamente l’autenticazione, si registra e apre la schermata di consenso.
- Il cliente accede al proprio account negozio e approva gli scope richiesti. Nessun token da inserire.
Collegare l’API Anthropic, Claude Desktop, Claude Code o n8n
- Apri la scheda Token di accesso, scegli gli scope e fai clic su Crea token.
- Copia il token mostrato.
- Configura il connettore con l’URL del server MCP e l’header
Authorization: Bearer IL_TUO_TOKEN.
Scope
Ogni accesso è limitato da scope, richiesti dall’agente e concessi al consenso (OAuth) o portati dal token (Bearer):
catalog:read— ricerca e schede prodotto, categorie, info negozio, corrieri.cart:write— creazione e gestione di carrelli.order:write— preparazione dell’ordine.
Strumenti esposti
Sono disponibili nove strumenti. Ciascuno si attiva o disattiva singolarmente nella scheda Impostazioni ed è soggetto allo scope corrispondente.
search_products— ricerca per parola chiave, riferimento o EAN, con filtri categoria e prezzo.get_product— scheda dettagliata di un prodotto (prezzo, stock, varianti, immagini).list_categories— albero delle categorie.get_shop_info— nome, lingue, valute e paesi di spedizione.get_carriers— corrieri disponibili.create_cart— creazione di un carrello.add_to_cart— aggiungere un prodotto al carrello.view_cart— contenuto e totali del carrello.create_order— finalizzazione, secondo la modalità d’ordine configurata.
Disattiva gli strumenti che non vuoi esporre. Per esempio, lasciare solo catalog:read e i suoi strumenti trasforma il modulo in un server di catalogo in sola lettura per gli agenti.
Modalità d’ordine
La scheda Impostazioni offre due comportamenti per create_order.
Modalità trasferimento (predefinita)
L’agente compone il carrello e restituisce un URL di pagamento sicuro. Seguendolo, il cliente ritrova esattamente quel carrello nella sua sessione e completa il pagamento sul consueto flusso di PrestaShop. Nessun dato di pagamento passa per l’agente: zero esposizione PCI.
Modalità ordine
L’agente crea direttamente un ordine in attesa di pagamento, nello stato configurabile (predefinito «Bonifico bancario in attesa»). Pensata per B2B, contrassegno o preventivi.
In modalità ordine, l’ordine viene creato senza pagamento incassato. Il pagamento viene poi raccolto secondo il metodo associato allo stato dell’ordine scelto.
Impostazioni aggiuntive
- Richiedere l’autenticazione: consigliato. Una richiesta non autenticata avvia il flusso OAuth (risposta 401 con header
WWW-Authenticate). - Lettura anonima del catalogo: consente chiamate
catalog:readsenza token, per esporre un catalogo pubblico. - Limite di frequenza: numero di richieste al minuto per IP (predefinito 120), a finestra scorrevole.
- Registrazione e conservazione: traccia ogni richiesta (metodo, strumento, stato, durata) nella scheda Registro attività, con un numero di righe conservate configurabile.
Rilevamento ed endpoint
Gli agenti rilevano il server automaticamente. Gli URL utili sono elencati nella scheda Collega un agente:
- Protected Resource Metadata (RFC 9728) —
/.well-known/oauth-protected-resource. - Authorization Server Metadata (RFC 8414) —
/.well-known/oauth-authorization-server. - Registrazione dinamica del client (RFC 7591), autorizzazione e token: endpoint OAuth gestiti dal modulo.
Anche senza URL semplificati, l’header WWW-Authenticate restituito dall’endpoint punta sempre al corretto URL di rilevamento basato su index.php: la connessione funziona in tutti i casi.
Sicurezza
- Tutti i token sono memorizzati con hash SHA-256, mai in chiaro.
- PKCE S256 obbligatorio,
redirect_uriconvalidati, codici di autorizzazione monouso, rotazione dei refresh token. - Limitazione di frequenza per IP e registro attività consultabile.
- CORS gestito per i connettori web. Compatibilità multinegozio, multilingua e multivaluta nativa.
Risoluzione dei problemi
- L’agente web non si collega: verifica che il negozio sia in HTTPS e che OAuth sia attivo. Assicurati di incollare l’URL
/mcp(non una pagina del back office). - Il client API restituisce 401: il token Bearer è assente, revocato o scaduto. Creane uno nuovo nella scheda Token di accesso e verifica l’header
Authorization. - Uno strumento non appare: è probabilmente disattivato in Impostazioni, oppure lo scope corrispondente non è stato concesso.
- Errore 429: il limite di frequenza per IP è raggiunto. Aumenta la soglia in Impostazioni se necessario.
- Il link di pagamento trasferito scade: i link del carrello hanno una durata limitata; chiedi all’agente di rigenerare il carrello.
Disinstallazione
La disinstallazione elimina le tabelle del modulo (token, client OAuth, carrelli, registro, limitatore) e le sue variabili di configurazione. I tuoi prodotti, clienti e ordini non sono interessati. Per un semplice aggiornamento, basta sostituire i file: lo schema e i token esistenti vengono conservati.