MCP Endpoint

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 su mcp.storekit.com. Ogni host di ordinazione storekit è anche un server MCP 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.

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.

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

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.

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

Il profilo che pubblicizza questi endpoint e la capability cart.

Strumenti WebMCP

Il set di strumenti separato che un agente chiama all’interno del browser del cliente.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

MCP Endpoint

Endpoint

Protocollo

Strumenti di lettura

Strumenti del carrello

Correlati

UCP discovery

Strumenti WebMCP

​Endpoint

​Protocollo

​Strumenti di lettura

​Strumenti del carrello

​Correlati

UCP discovery

Strumenti WebMCP

Endpoint

Protocollo

Strumenti di lettura

Strumenti del carrello

Correlati