MCP di Webround Commerce

Il server commerce dà a Claude le operazioni dell'API Commerce come strumenti: 269, in 31 gruppi. Tutto ciò che puoi fare con l'API, Claude lo fa se glielo chiedi.

https://ai-api.webround.com/mcp

Parla Streamable HTTP, senza sessioni.

Collega

Ogni richiesta porta tre intestazioni:

Intestazione	Valore
Authorization	Bearer <chiave API>: una chiave dello store, con i permessi che vuoi dare a Claude. Vedi API Keys.
store-id	L'ID dello store. È lo stesso del draft.
user-id	L'ID del proprietario dello store o di uno dei suoi collaboratori, come per l'API Commerce.

Con Claude Code:

claude mcp add --transport http webround-commerce "https://ai-api.webround.com/mcp?toolsets=catalog" \
  --header "Authorization: Bearer <chiave API>" \
  --header "store-id: <ID dello store>" \
  --header "user-id: <ID utente>"

Scegli gli strumenti

269 strumenti sono troppi perché un assistente li legga ogni volta, e la maggior parte delle conversazioni ne usa una parte. Uno strumento appartiene a un toolset, uno per ogni area dell'API (products, orders, promotions…). Scegli quali caricare con il parametro toolsets nell'indirizzo:

https://ai-api.webround.com/mcp?toolsets=products,orders

Oltre ai singoli toolset puoi usare un preset, un pacchetto con un nome di toolset che stanno bene insieme, così non devi sapere cosa dipende da cosa (una collezione vuole i filtri, un filtro vuole le condizioni):

Preset	A cosa serve
catalog	Prodotti, varianti, opzioni, tag, attributi, collezioni, filtri, asset, zone fiscali, zone e metodi di spedizione, magazzini. È ciò che ottieni se non chiedi niente.
orders	Ordini, righe d'ordine, resi, abbonamenti, clienti.
marketing	Promozioni, condizioni, feed, recensioni, analisi dei carrelli.
store-settings	Impostazioni dello store, checkout hook, webhook.
team	Collaboratori, ruoli, chiavi API, app.

Preset e singoli toolset si mescolano: ?toolsets=catalog,orders,promotions. Un nome che non esiste riceve un 400 con l'elenco di quelli che esistono. Ogni strumento è in Strumenti Commerce, con cosa fa e l'endpoint che c'è dietro.

Quando Claude si collega, il server gli dice quali toolset e preset esistono e come richiederli, così può dirti quando gliene serve uno che non hai caricato.

Cos'è uno strumento

Ogni strumento è un'operazione dell'API, con lo stesso nome e gli stessi parametri. Due cose non sono parametri, perché Claude non le sceglie mai: lo store (è lo store-id con cui ti sei collegato) e l'utente.

Il server segna ogni strumento per il client:

• Gli strumenti Read non cambiano niente.
• Gli strumenti Write aggiungono o aggiornano, senza togliere ciò che c'era.
• Gli strumenti Replace sovrascrivono ciò che c'era. Per esempio, lo strumento che sincronizza gli asset di un prodotto sostituisce tutta la lista.
• Gli strumenti Delete rimuovono dati.

Un client usa questi segni per decidere su cosa chiederti conferma prima di agire.

Come Claude crea un prodotto

Un prodotto con taglie e colori si crea in un'operazione sola, quindi o è completo o non esiste. Claude lo fa in tre passi:

1. Elenca le opzioni (gli assi, come Taglia e Colore) e i valori di tag (i valori, come S, M, rosso) che lo store ha già.
2. Crea ciò che manca: l'opzione, il tag e i valori di tag.
3. Crea il prodotto con una sola chiamata (create_product_aggregate): il prodotto, i valori di opzione che usa e una variante per ogni combinazione, ognuna con il suo prezzo, la sua giacenza e la sua combinazione di valori.

Se una variante cita una combinazione che il prodotto non ha, l'intera chiamata fallisce e non viene creato niente.

Permessi

Gli strumenti usano la chiave con cui ti sei collegato: una richiesta che la chiave non può fare riceve un errore dall'API e Claude te lo dice. Il server non amplia ciò che una chiave può fare. Per lo stesso motivo, una chiave per un assistente che deve solo leggere i prodotti dovrebbe avere solo i permessi di lettura dei prodotti.

Cosa non c'è

• Il caricamento dei file. Immagini e video si caricano con l'API Core. Claude può usare un asset già caricato.
• La vetrina. Carrello, login dei clienti, indirizzi, lista desideri e gli ordini del cliente sono per i browser dei tuoi clienti, non per un amministratore.
• Le operazioni vecchie. I checkout hook della versione precedente e /cart/total sono deprecati e non sono offerti.