# MCP server

# MCP server

The product exposes a [Model Context Protocol](https://modelcontextprotocol.io) server at `POST /mcp/bookings`, so AI agents (Claude, ChatGPT, custom tooling) can read and act on a company's live booking data through the same actions as the web app.

## Connecting

- **Endpoint:** `POST {app_url}/mcp/bookings` — JSON-RPC 2.0 over HTTP (`Accept: application/json, text/event-stream`).
- **Auth:** `Authorization: Bearer <personal-access-token>` — a Sanctum token created under **User settings → API tokens**. Every tool requires a matching token ability: `read` for lookups, `create`/`update`/`delete` for writes. A token without the ability gets `forbidden`.
- **Scope:** all tools run in the authenticated user's company — a token can never reach another tenant.
- **Throttle:** the endpoint is rate-limited (`throttle:sync`); bursts should stay under one request per second.

## Methods

Standard MCP method surface: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get`.

## Tools

31 tools, all enforcing the same validation, capacity and package gates as the web app:

| Group | Tools |
|---|---|
| Events | `list-events`, `get-event`, `list-event-types`, `next-available-event`, `publish-event` |
| Bookings | `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` |
| Availability | `get-availability`, `find-slot` |
| Venue | `list-areas`, `list-tables`, `list-venue-items` |
| Orders & menu | `list-orders`, `get-order`, `list-menu-items`, `toggle-menu-item-sold-out` |
| Waitlist & guests | `list-waitlist-entries`, `offer-waitlist-spot`, `get-guest` |
| Inquiries | `list-inquiries`, `convert-inquiry` |
| Stock & KPIs | `get-stock-levels`, `get-kpi` |

Write tools are real writes — `create-booking` reserves capacity immediately, `offer-waitlist-spot` sends the offer. There is no sandbox mode: use a test company for experimentation.

## Resources

Read-only markdown content gated by the caller's role and token abilities:

- `docs://catalog` — the documentation index visible to the token's user.
- `docs://{category}/{slug}` — one documentation page as markdown (e.g. `docs://developer/api-tokens`). Role-gated exactly like the docs hub: a page the user cannot see returns `not_found`.
- `changelog://index` — public release list.

## Prompts

Ready-made operational workflows that instruct the client which tools to call — they never write by themselves:

- `daily-service-brief` — pre-service digest for a date (bookings, closures, pending approvals, KPIs).
- `fill-cancelled-slot` — backfill a cancelled booking from the waitlist (`booking_code` required).
- `weekly-ops-review` — week-in-review digest.
- `venue-health-check` — read-only setup audit (published events, floor plan, availability).

## Errors and limits

Errors come back as JSON-RPC errors (`invalid params`, `method not found`) or as tool payloads containing an `error` key — check `result.content[].text` for `{error: "..."}` objects. Tenant safety mirrors the app: foreign ids resolve as `*_not_found`, never as data leaks.


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