Model Context Protocol
Let approved AI clients use venue context.
Keep authority on the server.
- HTTP transport
- API-key scopes
- Audited tools
Quick start
A standard JSON-RPC request
Use a Booking Bible API key whose plan and provisioning allow API access. Rate limits follow that key’s configured API allowance.
curl https://bookingbible.com/api/mcp \
--request POST \
--header "Content-Type: application/json" \
--header "X-API-Key: bb_live_..." \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "search_schedule",
"arguments": { "date": "2026-07-28" }
}
}To create Flash Sales, issue a new custom API key with write:marketing. Keys created before writable MCP tools were introduced must be reissued so the server can retain the creating staff identity for the audit trail.
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "create_flash_sale",
"arguments": {
"name": "Autumn membership offer",
"commercial_rule": {
"version": 2,
"kind": "introductory_price",
"pricing": { "mode": "shared", "price": 99 },
"currency": "DKK",
"vatMode": "included",
"waiveRegistrationFeePassTypeIds": [],
"duration": { "mode": "until_date", "endsAt": "2026-10-01" },
"followingPrice": { "mode": "pass_price" }
},
"product_family": "recurring",
"applicable_pass_type_ids": ["00000000-0000-4000-8000-000000000000"],
"starts_at": "2026-08-25T00:00:00.000Z",
"ends_at": "2026-10-01T00:00:00.000Z",
"placements": ["public_link", "pricing_page", "global_app"]
}
}
}Venue administration tools (cancel, check in, no-show, book a member, freeze, unfreeze or extend a pass, staff notes) need write:bookings, write:checkin, write:pass_lifecycle or write:members. Each call carries an operation_key: reuse it only to retry the exact same change.
Resources
Addressable, venue-scoped views
Resource URIs carry only the requested view parameters. The authenticated API key supplies the venue boundary.
| URI template | Purpose | Required scope |
|---|---|---|
| venue://schedule/{date} | Daily schedule | read:schedule |
| venue://classes/{date_range} | Class instances by date range | read:schedule |
| venue://members/{query} | Member search | read:members |
| venue://member/{id} | Member detail | read:members |
| venue://passes | Active pass types | read:passes |
| venue://bookings/{date} | Bookings for date | read:bookings |
| venue://revenue/{period} | Revenue summary | read:reports |
| venue://alerts | Active alerts | read:operations |
Tools
Narrow operations with explicit schemas
The client discovers JSON input schemas through tools/list. The server validates every call before querying venue data.
search_scheduleFind classes on a date, optionally filtered by class type or instructor name. Returns up to 100 instances.
read:schedule
check_availabilityReturns capacity, current bookings, and remaining seats for a class instance.
read:schedule
search_membersSearch venue members by name, email, or client display ID. Returns up to 25 matches.
read:members
get_member_detailsFull member profile with active passes and most recent bookings.
read:members
get_revenue_summaryRevenue totals by currency for a period (today / week / month / YYYY-MM-DD..YYYY-MM-DD).
read:reports
get_today_overviewToday's class count + booking count + open alert count — fast snapshot for an AI assistant's home view.
read:schedule + read:bookings + read:operations
create_flash_saleCreate a venue-scoped Flash Sale offer. This tool never creates or sends a marketing campaign.
write:marketing
cancel_bookingCancel one booking with the venue's cancellation core: a class used from a pass goes back, an unpaid late-cancel or no-show fee on it is cancelled, a freed seat goes to the waitlist. Silent unless notify_channels is set.
write:bookings
check_in_bookingCheck in one booked client under the venue's check-in rules.
write:checkin
mark_no_showMark one booking as a no-show under the venue's no-show rules (fees included).
write:checkin
book_member_into_classBook an active member into a class with the venue's booking engine (pass rules, capacity and waitlist apply; no capacity override). The member is not notified.
write:bookings
freeze_passFreeze an active pass or membership from pause_start to pause_end (both included); a membership's payments are adjusted for the frozen days.
write:pass_lifecycle
unfreeze_passUnfreeze a frozen pass or cancel a planned freeze.
write:pass_lifecycle
extend_passExtend a pass's end date by days, as staff from the client pass screen: the pass type's hard end caps it and a pass without an end date is refused. Silent. A retry with the same operation_key is answered from the first run.
write:pass_lifecycle
add_member_noteAdd an internal staff note to a member's profile (never shown to the member). Reuse operation_key only for the same note; a replay confirms already_applied without another append.
write:members
search_paymentsRecent payments for this venue (optionally one member's), newest first, with amount, currency and status. Refunds are confirmed by a person on the payment page (/admin/payments/{id}).
read:payments
Security boundary
Useful context with explicit authority
MCP does not bypass the API access gate, key scopes, tenant isolation, rate limits or the platform’s emergency kill switch.
One scoped API key
The server reuses Booking Bible API keys. Every resource and tool declares the exact read or write scopes it requires.
Venue scope from authentication
The organization comes from the authenticated key, never from a model-provided URI or tool argument.
Audited and row-capped
Tool calls pass through the AI audit chokepoint and enforce per-tool result ceilings before returning data.
Narrow writes by design
Write tools run the same server-side cores as the admin screens, as the person who issued the key and with that person’s current permissions. Clients are told only when a call names notice channels. Flash Sale creation cannot send a campaign, email or SMS, and no MCP tool moves money: refunds are confirmed by a person on the payment page.
Build with the right surface
MCP for contextual reads and narrow operations. REST for full application workflows.
Use the least-privileged key for the work at hand. Add a write scope only for the changes the client must make (write:marketing for Flash Sales, write:pass_lifecycle for pass freezes and extensions), and keep unrelated write scopes off that key.