> ## 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.

# Server MCP

> I due server Model Context Protocol di Vellaro, sopra la stessa REST API.

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](#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.

```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>" }
    }
  }
}
```

### 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.

<Warning>
  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.
</Warning>

<Note>
  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](/authentication).
</Note>