> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vellaro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI & MCP

> Usa Vellaro come connettore per i motori AI tramite Model Context Protocol.

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
**fare acquisti** sul negozio, sia **gestire** il negozio — con la stessa API e le stesse
regole di sicurezza del resto della piattaforma.

<CardGroup cols={2}>
  <Card title="Storefront MCP" icon="cart-shopping">
    Commerce conversazionale: cerca prodotti, gestisci il carrello, avvia il checkout,
    traccia gli ordini. Auth con **chiave publishable**.
  </Card>

  <Card title="Admin MCP" icon="gear">
    Gestione via linguaggio naturale: catalogo, prezzi, stock, ordini. Auth con **token
    staff** + permessi, con conferme sulle azioni sensibili.
  </Card>
</CardGroup>

## Storefront MCP

Pensato per client pubblici/agenti che comprano per conto dell'utente. Tool principali:

| Tool                        | Cosa fa                      |
| --------------------------- | ---------------------------- |
| `search_products`           | ricerca full-text con filtri |
| `get_product`               | dettaglio prodotto/varianti  |
| `list_categories`           | albero categorie             |
| `add_to_cart` / `view_cart` | gestione carrello            |
| `get_payment_methods`       | metodi disponibili           |
| `create_checkout`           | avvia l'ordine               |
| `track_order`               | stato di un ordine           |

Auth: la **chiave publishable** del negozio (`cx_pk_live_...`) — identifica il negozio, non
può toccare l'admin.

## Admin MCP

Pensato per operatori/integrazioni: *"alza del 5% i prezzi dell'elettronica e disattiva gli
esauriti"*. Tool principali:

| Tool                                  | Cosa fa                         |
| ------------------------------------- | ------------------------------- |
| `list_products` / `get_product`       | catalogo (inclusi inattivi)     |
| `create_product` / `update_product`   | crea/aggiorna                   |
| `set_price` / `set_stock`             | prezzo/giacenza di una variante |
| `list_orders` / `update_order_status` | ordini e fulfillment            |

**Sicurezza** — eredita il modello della Admin API:

* Auth con **token staff** + permessi granulari; ogni azione vincolata al **suo negozio**.
* Le **mutazioni** richiedono conferma esplicita e sono **audit-loggate**.
* Il token staff non va mai in un client pubblico.

## Come collegarsi

Un client MCP (es. Claude Desktop) si configura con l'endpoint del server e le credenziali:

```json theme={null}
{
  "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>" }
    }
  }
}
```

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:

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

<Note>
  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](/api-reference) resta la
  fonte di verità. Dettagli auth e caveat in [Server MCP](/api-reference/mcp).
</Note>