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

# Panoramica del merchant MCP

> Server MCP remoto e limitato all'account che dà a un client AI accesso in lettura a ordini, menu, statistiche e conti storekit, più due scritture.

**A chi si rivolge:** uno sviluppatore che collega un client o un agente AI all'account storekit di un merchant. Per le superfici lato cliente (un agente che legge un menu pubblico e costruisce un basket) consulta [Agenti di ordinazione](/docs/it/developers/agents/ordering/overview). Per le guide di configurazione non tecniche, consulta [Collega il tuo agente AI](/docs/it/guides/ai/overview).

> [!NOTE]
>
> **Funzionalità beta** - Il merchant MCP è in beta e gli account vengono abilitati da una waitlist. [Richiedi l'accesso](https://t09czsyu90l.typeform.com/to/G6rIJWNv), oppure scrivi a [mcp@storekit.com](mailto:mcp@storekit.com).

## Endpoint

| | |
| - | - |
| URL | `https://mcp.storekit.com/mcp` |
| Transport | MCP [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), risposte JSON (nessuno streaming SSE) |
| Metodi | `POST` per i messaggi JSON-RPC; `GET` e `DELETE` come da specifica del transport |
| Sessione | Stateless. `initialize` restituisce un header `Mcp-Session-Id`, ma le richieste non vengono validate contro di esso |
| Auth | Bearer token OAuth 2.1: consulta [Autenticazione](/docs/it/developers/mcp/authentication) |
| Discovery | `GET /.well-known/oauth-protected-resource` |

Ogni richiesta crea un nuovo server MCP legato all'account autenticato, gestisce un messaggio e si chiude. Nulla viene ricordato tra le chiamate; una conversazione porta con sé gli ID dei locali e degli ordini.

## Strumenti

Diciotto strumenti, tutti limitati all'account autenticato. Sedici sono di sola lettura (`readOnlyHint: true`); `create-discount-code` e `create-payment-link` sono scritture. Il riferimento completo degli input è in [Strumenti](/docs/it/developers/mcp/tools).

| Dominio | Strumenti |
| - | - |
| Locali | `list-venues`, `get-venue` |
| Ordini | `list-orders`, `get-order`, `get-order-events` |
| Menu | `list-menus`, `get-menu` |
| Snooze | `get-snooze-report` |
| Statistiche | `get-order-stats`, `list-top-products` |
| Sconti | `list-discount-codes`, `create-discount-code` |
| Rimborsi | `list-refunds` |
| Pay at table | `list-bills` |
| Payment link | `list-payment-links`, `get-payment-link`, `create-payment-link`, `get-payment-link-qr` |

Non esistono strumenti che modifichino ordini, menu, locali, utenti o impostazioni.

## Contratto in breve

* Ogni successo è un envelope `{ data, meta }`, restituito sia come `structuredContent` sia come JSON nel primo blocco di testo. Ogni strumento pubblica un `outputSchema` corrispondente. Consulta [Formato della risposta](/docs/it/developers/mcp/response-format).
* Gli errori sono risultati `isError: true` solo testo che portano un envelope `{ error }` con un `code` stabile. Consulta [Errori](/docs/it/developers/mcp/errors).
* Gli importi monetari sono in **unità minori** con un codice valuta esplicito. Le date sono ISO strict. Le query limitate a un locale usano di default il fuso orario del locale, quelle a livello di account usano UTC.
* La paginazione parte da pagina 1, è limitata a 100 righe, e riporta `hasMore`/`nextPage` da un lookahead di una riga anziché dai totali.

## Limiti

| Limite | Valore |
| - | - |
| Rate | 60 richieste al minuto per utente; `429` con `Retry-After` oltre questo limite |
| Timeout dello strumento | 30 secondi; una scrittura in timeout potrebbe comunque essersi completata |
| Dimensione della pagina | 100 righe (25 per `list-top-products`) |
| Intervallo di date | 90 date di calendario locali, inclusive |
| Eventi snooze per articolo | 100, contrassegnati con `eventsTruncated` |

## Riferimento

> **[Autenticazione](/docs/it/developers/mcp/authentication)**
>
> Discovery OAuth e sign-in, come viene scelto l'account.

> **[Strumenti](/docs/it/developers/mcp/tools)**
>
> Ogni strumento con i suoi input, i default e la base delle date.

> **[Formato della risposta](/docs/it/developers/mcp/response-format)**
>
> L'envelope, la paginazione, le date, i fusi orari e la valuta.

> **[Errori](/docs/it/developers/mcp/errors)**
>
> Codici di errore, regole di retry e le forme che i client devono gestire.


## Related topics

- [Introduzione per sviluppatori](/docs/it/developers/introduction.md)
- [Panoramica degli agenti di ordinazione](/docs/it/developers/agents/ordering/overview.md)
- [MCP Endpoint](/docs/it/developers/agents/ordering/mcp-endpoint.md)
- [Dispatch aggregato con First Delivery](/docs/it/guides/integrations/delivery/first-delivery.md)
- [Panoramica del menu](/docs/it/guides/menu/overview.md)


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