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

# MCP Endpoint

> Collega un assistente AI a un negozio storekit tramite MCP: leggi menu, opzioni, metodi di fulfillment e slot orari, e costruisci un carrello con prezzi.

**A chi si rivolge:** un'app assistente o agente che agisce per conto del cliente, al di fuori del suo browser. Se l'assistente agisce per conto del ristorante, ti serve invece il [merchant MCP](/docs/it/developers/mcp/overview) su `mcp.storekit.com`.

Ogni host di ordinazione storekit è anche un server [MCP](https://modelcontextprotocol.io) remoto. Un assistente che non si trova affatto vicino al browser del cliente (ChatGPT, Claude, un'app agente, un IDE) può collegarsi ad esso, leggere il menu di un locale, ottenere un prezzo e costruire un carrello che il cliente aprirà poi per pagare.

## Endpoint

Ci sono due ambiti, entrambi raggiungibili sull'host di ordinazione del negozio stesso:

| Endpoint | Ambito |
| - | - |
| `POST https://{host}/{venueSlug}/api/mcp` | Un locale, per un agente che sta già parlando di una location |
| `POST https://{host}/api/mcp` | Ogni locale del brand su quell'host, risolto per chiamata |

`{host}` è il dominio dal quale sono servite le pagine di ordinazione del negozio, ad esempio `order.storekit.com`. Entrambi gli endpoint sono limitati a quell'host, quindi un brand sul proprio dominio può rispondere solo per i propri locali.

Usa l'endpoint del brand quando il cliente non ha detto quale sede vuole: `find_venues` restituisce lo slug che tutti gli altri strumenti prendono poi come argomento `venue`. Usa l'endpoint del locale quando la location è già decisa.

Una `GET` o `HEAD` su uno dei due endpoint restituisce `200` e una riga che dice cos'è l'endpoint, così un client può sondarlo prima di aprire una sessione.

## Protocollo

JSON-RPC 2.0 su HTTP, un messaggio per `POST`. I metodi implementati sono `initialize`, `ping`, `tools/list` e `tools/call`; le revisioni MCP `2025-06-18`, `2025-03-26` e `2024-11-05` vengono tutte gestite nella revisione richiesta dal client.

```bash theme={null}
curl -X POST https://order.storekit.com/gordon-ramsay-plane-food-1/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_menu",
      "arguments": { "query": "something vegan" }
    }
  }'
```

Ogni risultato è JSON in un blocco di contenuto testo, ripetuto come `structuredContent` per i client che lo leggono. L'endpoint è stateless: `initialize` non restituisce alcun session id e nulla viene ricordato tra le richieste, quindi una conversazione porta con sé lo slug del locale e l'id del carrello anziché una sessione.

Gli errori si dividono in base a chi può agire su di essi. Un argomento malformato è un JSON-RPC `-32602` che nomina il parametro; qualsiasi cosa da cui l'assistente possa recuperare (nessuna categoria di quel tipo, nessuna corrispondenza, un locale che ha smesso di accettare ordini) torna come risultato dello strumento con `isError: true` il cui testo dice cosa fare dopo.

## Strumenti di lettura

| Strumento | Descrizione |
| - | - |
| `find_venues` | Elenca i locali del brand, filtrati per nome, città o codice postale. Restituisce lo slug che gli altri strumenti prendono. |
| `get_menu` | Il menu del locale: ogni categoria con i suoi articoli, prezzi, tag dietetici e disponibilità. Un menu molto lungo viene riassunto, e un nome di categoria restituisce quella categoria per intero. |
| `search_menu` | Cerca nel menu per nome del piatto, categoria o descrizione. Per menu troppo lunghi da restituire per intero. |
| `get_item` | Un articolo per intero: gli allergeni che contiene e che potrebbe contenere (`allergens.contains`, `allergens.mayContain`, dai 14 allergeni UK; `null` quando il locale non ha dichiarato nulla, liste vuote quando ha dichiarato l'articolo privo di allergeni), i valori nutrizionali dove il locale li pubblica (`nutrition`: kcal, poi grammi; `null` altrimenti), quante porzioni serve in un locale di catering (`servings`), e ogni gruppo di opzioni, quante scelte accetta e quanto costa ciascuna. Entrambi i campi descrivono l'articolo base; un'opzione che aggiunge allergeni o valori nutrizionali porta con sé i propri `allergens` / `nutrition`. |
| `get_venue_info` | Il locale stesso: nome, indirizzo, numero di telefono, sito web, descrizione, se è aperto ora, gli orari di oggi, gli orari di apertura dell'intera settimana (schema.org `OpeningHoursSpecification`) e i metodi di ordinazione offerti. |
| `get_available_fulfillment` | Come si può ordinare dal locale, la spesa minima per ogni metodo, se è aperto ora e gli orari di oggi. |
| `get_available_slots` | Gli slot di consegna o ritiro ancora liberi in una determinata giornata. |

`get_menu` e `search_menu` accettano entrambi liste opzionali `excludeAllergens` e `diets`. `excludeAllergens` nomina uno qualsiasi dei 14 allergeni UK (`celery`, `gluten`, `crustaceans`, `fish`, `eggs`, `lupin`, `milk`, `molluscs`, `mustard`, `nuts`, `peanuts`, `sesame`, `soya`, `sulphites`) e lascia fuori ogni articolo che contiene o potrebbe contenere uno di essi; un articolo senza informazioni sugli allergeni viene mantenuto, dato che non taggato non è la stessa cosa di privo di quell'allergene. `diets` nomina uno qualsiasi tra `halal`, `kosher`, `vegan`, `vegetarian`, `gluten free` e `dairy free`, e mantiene solo gli articoli taggati come adatti a ognuno di essi. Sono le stesse regole che la pagina di ordinazione applica ai propri filtri di allergeni e diete, e il risultato ripete i filtri che ha applicato sotto `filters`.

Sull'endpoint del brand ogni strumento tranne `find_venues` prende un argomento extra `venue`, e uno slug che non appartiene a quel brand viene rifiutato con la lista del brand stesso anziché essere risposto dal menu di un altro brand.

Le letture portano `readOnlyHint`, quindi un client può chiamarle senza chiedere prima al cliente. I prezzi sono stringhe formattate nella valuta del locale, le descrizioni sono ripulite e troncate, e ogni lista ha un limite.

> [!NOTE]
>
> I metodi di fulfillment vengono riportati in base a ciò che il payload del locale dimostra: Delivery, Pickup e InStore. Il Catering non è offerto tramite MCP.

## Strumenti del carrello

La capability cart segue esattamente il [binding UCP cart MCP](https://ucp.dev/2026-08-25/specification/shopping/cart/mcp/), quindi un client UCP non ha bisogno di alcuna tabella di mapping.

| Strumento | Descrizione |
| - | - |
| `create_cart` | Costruisce un carrello in questo locale partendo dagli articoli del menu, con prezzi nella valuta del locale. |
| `get_cart` | Rilegge e ricalcola i prezzi di un carrello tramite id. |
| `update_cart` | Sostituisce le righe del carrello. È una sostituzione completa, non una patch: invia ogni riga che il carrello deve contenere. |
| `cancel_cart` | Scarta il carrello. |

Cosa significa in pratica il binding:

* Ogni chiamata porta `meta["ucp-agent"]` con il profilo del tuo agente. Una chiamata senza di esso viene rifiutata.
* L'id del carrello è un `id` di primo livello, mai annidato dentro `cart`.
* Gli importi sono interi in unità minori (`450` è £4.50).
* Un problema di business è un risultato di successo che porta `messages[]`: una riga che ha smesso di essere vendibile viene riportata lì anziché sparire.
* Le righe sono identificate per id articolo con le opzioni tra parentesi, `BURGER(CHEESE;BACON:2)`, la stessa grammatica utilizzata dai [link di prefill del basket](/docs/it/developers/basket-prefill).

Un carrello contiene un'intenzione, non prezzi: ogni operazione lo risolve nuovamente e ricalcola i prezzi rispetto al menu attuale, così un carrello memorizzato non può proporre una cifra che la pagina del locale contraddirebbe. I carrelli scadono 24 ore dopo la loro ultima scrittura, e nulla di legato al cliente vi viene memorizzato.

> [!WARNING]
>
> Un carrello non è un ordine, e questi strumenti parlano solo per il lato del cliente. Nulla qui legge la coda di ordini di un negozio, modifica un menu o cambia un'impostazione. Gli strumenti restituiscono un `continue_url` che il cliente apre per rivedere il carrello e pagare sulla pagina del locale: non c'è alcuno strumento di checkout, pagamento o sconto, e nessun ordine viene effettuato finché il cliente non termina lì.

## Correlati

> **[UCP discovery](/docs/it/developers/agents/ordering/ucp)**
>
> Il profilo che pubblicizza questi endpoint e la capability cart.

> **[Strumenti WebMCP](/docs/it/developers/agents/ordering/webmcp)**
>
> Il set di strumenti separato che un agente chiama all'interno del browser del cliente.


## Related topics

- [Introduzione per sviluppatori](/docs/it/developers/introduction.md)
- [Panoramica degli agenti di ordinazione](/docs/it/developers/agents/ordering/overview.md)
- [Panoramica del merchant MCP](/docs/it/developers/mcp/overview.md)
- [Autenticazione](/docs/it/developers/mcp/authentication.md)
- [Discovery UCP](/docs/it/developers/agents/ordering/ucp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.