# DataFirefly MCP Commerce — Guida completa > 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 —… - Pagina: - Lingua: it - Aggiornato il: 2026-06-17 - Altre lingue: [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), [de](https://www.datafirefly.com/de/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) - Indice: 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 1. Nel back office, apri _Moduli > Gestore moduli_, poi _Carica un modulo_ e rilascia il file `dfmcpcommerce.zip`. 2. Una volta installato, apri la configurazione tramite il pulsante _Configura_. 3. 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) 1. Mantieni **OAuth 2.1** attivo nella scheda _Impostazioni_. 2. Nell'agente, aggiungi un connettore personalizzato e incolla l'URL del server MCP. 3. L'agente scopre automaticamente l'autenticazione, si registra e apre la schermata di consenso. 4. 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 1. Apri la scheda _Token di accesso_, scegli gli scope e fai clic su **Crea token**. 2. Copia il token mostrato. 3. 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:read` senza 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_uri` convalidati, 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.