Server MCP

Il prodotto espone un server Model Context Protocol su POST /mcp/bookings, così agenti AI (Claude, ChatGPT, strumenti personalizzati) possono leggere e agire sui dati live delle prenotazioni di un'azienda attraverso le stesse action dell'app web.

Connessione

• Endpoint: POST {app_url}/mcp/bookings — JSON-RPC 2.0 su HTTP (Accept: application/json, text/event-stream).
• Auth: Authorization: Bearer <personal-access-token> — un token Sanctum creato in Impostazioni utente → Token API. Ogni tool richiede l'ability corrispondente: read per le letture, create/update/delete per le scritture. Un token senza ability riceve forbidden.
• Scope: tutti i tool girano nel contesto aziendale dell'utente autenticato — un token non può mai raggiungere un altro tenant.
• Throttle: l'endpoint è rate-limited (throttle:sync); resta sotto una richiesta al secondo.

Metodi

Superficie MCP standard: initialize, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, prompts/get.

Tool

31 tool, tutti con le stesse validazioni, limiti di capacità e vincoli di pacchetto dell'app web:

Gruppo	Tool
Eventi	list-events, get-event, list-event-types, next-available-event, publish-event
Prenotazioni	list-bookings, get-booking, search-bookings, create-booking, update-booking, cancel-booking, list-pending-approvals, check-in-booking, mark-booking-service, assign-table-to-booking
Disponibilità	get-availability, find-slot
Locale	list-areas, list-tables, list-venue-items
Ordini e menu	list-orders, get-order, list-menu-items, toggle-menu-item-sold-out
Lista d'attesa e ospiti	list-waitlist-entries, offer-waitlist-spot, get-guest
Richieste	list-inquiries, convert-inquiry
Magazzino e KPI	get-stock-levels, get-kpi

I tool di scrittura scrivono davvero — create-booking riserva capacità immediatamente, offer-waitlist-spot invia l'offerta. Non esiste modalità sandbox: usa un'azienda di prova per sperimentare.

Risorse

Contenuti markdown in sola lettura, filtrati per ruolo e ability del chiamante:

• docs://catalog — l'indice della documentazione visibile all'utente del token.
• docs://{category}/{slug} — una pagina di documentazione in markdown (es. docs://developer/api-tokens). Stesso gating del docs hub: una pagina che l'utente non può vedere risponde not_found.
• changelog://index — lista dei rilasci pubblici.

Prompt

Flussi operativi già pronti che istruiscono il client su quali tool chiamare — non scrivono mai da soli:

• daily-service-brief — digest pre-servizio per una data (prenotazioni, chiusure, approvazioni in sospeso, KPI).
• fill-cancelled-slot — riempi il vuoto di una prenotazione annullata dalla lista d'attesa (booking_code obbligatorio).
• weekly-ops-review — digest settimanale.
• venue-health-check — audit di configurazione in sola lettura (eventi pubblicati, pianta, disponibilità).

Errori e limiti

Gli errori tornano come errori JSON-RPC (invalid params, method not found) o come payload del tool con chiave error — controlla result.content[].text per oggetti {error: "..."}. La sicurezza tenant replica l'app: gli id altrui risolvono come *_not_found, mai come fughe di dati.