Skip to main content

Model Context Protocol

Let approved AI clients use venue context.
Keep authority on the server.

Booking Bible exposes a stateless JSON-RPC endpoint using MCP protocol 2025-03-26. It is a venue-scoped interface over selected data and narrowly permissioned operations.
  • 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.

bash
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"
  }'
json
{
  "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.

json
{
  "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 templatePurposeRequired scope
venue://schedule/{date}Daily scheduleread:schedule
venue://classes/{date_range}Class instances by date rangeread:schedule
venue://members/{query}Member searchread:members
venue://member/{id}Member detailread:members
venue://passesActive pass typesread:passes
venue://bookings/{date}Bookings for dateread:bookings
venue://revenue/{period}Revenue summaryread:reports
venue://alertsActive alertsread: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_schedule

Find classes on a date, optionally filtered by class type or instructor name. Returns up to 100 instances.

read:schedule

check_availability

Returns capacity, current bookings, and remaining seats for a class instance.

read:schedule

search_members

Search venue members by name, email, or client display ID. Returns up to 25 matches.

read:members

get_member_details

Full member profile with active passes and most recent bookings.

read:members

get_revenue_summary

Revenue totals by currency for a period (today / week / month / YYYY-MM-DD..YYYY-MM-DD).

read:reports

get_today_overview

Today'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_sale

Create a venue-scoped Flash Sale offer. This tool never creates or sends a marketing campaign.

write:marketing

cancel_booking

Cancel 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_booking

Check in one booked client under the venue's check-in rules.

write:checkin

mark_no_show

Mark one booking as a no-show under the venue's no-show rules (fees included).

write:checkin

book_member_into_class

Book 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_pass

Freeze 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_pass

Unfreeze a frozen pass or cancel a planned freeze.

write:pass_lifecycle

extend_pass

Extend 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_note

Add 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_payments

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