# Server MCP

# Server MCP

Il prodotto espone un server [Model Context Protocol](https://modelcontextprotocol.io) 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.


---
> Source: https://placeful-app.com/docs/developer/mcp-server