Server MCP - Vellaro

Oltre alla REST API, Vellaro espone due server Model Context Protocol (MCP) su mcp.vellaro.io. Un agente AI può così interrogare e operare sul negozio con la stessa auth, gli stessi permessi e lo stesso isolamento tenant degli endpoint HTTP documentati qui.

Endpoint

Server	Endpoint	Auth
Storefront	`https://mcp.vellaro.io/storefront`	header `X-Vellaro-Key: cx_pk_live_...` — oppure `?key=` nell’URL (vedi Collegamento)
Admin	`https://mcp.vellaro.io/admin`	header `Authorization: Bearer <staff_token>`

Trasporto streamable-HTTP (stateless). Nessun segreto è memorizzato: la credenziale viaggia negli header della richiesta MCP e viene inoltrata verbatim alla REST API.

Storefront MCP

Auth con la chiave publishable del negozio (cx_pk_live_...) — identifica il negozio e non può toccare gli endpoint /admin/*.

Tool	Cosa fa
`search_products`	ricerca full-text con filtri
`list_products` / `get_product`	catalogo e dettaglio varianti
`list_categories`	albero categorie
`store_info`	dati e aspetto del negozio
`payment_methods`	metodi di pagamento disponibili
`track_order`	stato di un ordine

Admin MCP

Auth con token staff + permessi granulari; ogni azione è vincolata al suo negozio. Le mutazioni richiedono confirm=true e sono audit-loggate.

Tool	Cosa fa
`list_products` / `get_product`	catalogo (inclusi inattivi)
`create_product`	crea un prodotto
`set_price` / `set_stock`	prezzo/giacenza di una variante (assoluti)
`adjust_stock`	variazione relativa di giacenza
`list_orders` / `get_order`	ordini
`update_order_status`	avanzamento/fulfillment ordine

Collegamento

Client con header (Claude Desktop, Claude Code)

Il modo consigliato: l’endpoint del server + la credenziale negli header.

{
  "mcpServers": {
    "vellaro-storefront": {
      "url": "https://mcp.vellaro.io/storefront",
      "headers": { "X-Vellaro-Key": "cx_pk_live_<slug>_..." }
    },
    "vellaro-admin": {
      "url": "https://mcp.vellaro.io/admin",
      "headers": { "Authorization": "Bearer <staff_token>" }
    }
  }
}

Connettore claude.ai (chiave nell’URL — solo storefront)

Il dialog “connettore personalizzato” di claude.ai supporta solo OAuth, non gli header custom. Per lo storefront puoi passare la chiave publishable direttamente nell’URL:

https://mcp.vellaro.io/storefront/?key=cx_pk_live_<slug>_...

Lascia vuoti i campi OAuth (Client ID / Secret). L’header ha comunque la priorità: se il client invia X-Vellaro-Key, la query string viene ignorata.

Solo storefront. La chiave publishable è read-only (come una pk_ di Stripe) ed è accettabile in un URL, ma comparirà nei log di accesso del server. L’admin resta header-only: un token staff non deve mai finire in un URL.

I server MCP sono un thin layer sopra questa stessa REST API: qualsiasi cosa faccia un tool, la puoi fare via HTTP. Gli endpoint elencati in questa sezione restano la fonte di verità. Vedi anche Autenticazione.

​Endpoint

​Storefront MCP

​Admin MCP

​Collegamento

​Client con header (Claude Desktop, Claude Code)

​Connettore claude.ai (chiave nell’URL — solo storefront)

Endpoint

Storefront MCP

Admin MCP

Collegamento

Client con header (Claude Desktop, Claude Code)

Connettore claude.ai (chiave nell’URL — solo storefront)