Vai al contenuto principale
Il Model Context Protocol (MCP) è lo standard con cui gli agenti AI (Claude e altri) si collegano a strumenti e dati esterni. Vellaro espone due server MCP, così un agente può sia consultare il negozio come un cliente, sia gestirlo — con la stessa API e le stesse regole di sicurezza del resto della piattaforma.

Storefront MCP

Commerce conversazionale: cerca prodotti, consulta catalogo, metodi di pagamento e dati del negozio, traccia gli ordini. Auth con chiave publishable.

Admin MCP

Gestione via linguaggio naturale: catalogo, prezzi, stock, ordini. Auth con token staff + permessi, con conferme sulle azioni sensibili.

Storefront MCP

Pensato per client pubblici e agenti che aiutano l’utente a scegliere e seguire un acquisto. Tool disponibili: Auth: la chiave publishable del negozio (cx_pk_live_...) — identifica il negozio, non può toccare l’admin.

Admin MCP

Pensato per operatori e integrazioni: “alza del 5% i prezzi dell’elettronica e azzera lo stock degli articoli fuori produzione”. Tool disponibili:
update_order_status con status: "refunded" su un ordine pagato rimborsa davvero il residuo al cliente sul gateway di pagamento: non è un’etichetta, muove denaro, come il rimborso dal pannello. Serve un ruolo che può rimborsare (admin, manager, sales_manager), altrimenti l’API risponde 403 order.refund_forbidden. Su un ordine non incassato usa cancelled.
Sicurezza — eredita il modello della Admin API:
  • Auth con token staff + permessi granulari; ogni azione vincolata al suo negozio.
  • Le mutazioni richiedono confirm=true (prima l’agente vede cosa farebbe, poi conferma) e sono audit-loggate.
  • Il token staff non va mai in un client pubblico.
Un access token staff scade dopo 30 minuti. Per un agente collegato a lungo usa un token API del negozio, con il ruolo minimo che serve: si genera da POST /admin/api-tokens e si revoca all’istante. Vedi Gestisci il negozio via API.

Come collegarsi

Un client MCP (es. Claude Desktop) si configura con l’endpoint del server e le credenziali:
Con il connettore personalizzato di claude.ai (che supporta solo OAuth, non gli header), per lo storefront passa la chiave publishable nell’URL — campi OAuth vuoti:
I server MCP sono un thin layer sopra la stessa REST API documentata qui: qualsiasi cosa faccia un tool, la puoi fare anche via HTTP. La API Reference resta la fonte di verità. Dettagli auth e caveat in Server MCP.