Developer docs

What the tools do

What an assistant can and cannot do with the BookDinePlay MCP server — guest booking, operator tools, the confirmation pattern and the guided venue sign-up.

A tool is one action the assistant may take. Each carries four hints that clients show you before they run it: whether it only reads, whether it can destroy data, whether repeating it is harmless and whether it reaches outside BookDinePlay (it sends an e-mail or talks to Stripe). Your client may ask you to approve a call that is not read-only.

Guest tools

Every signed-in person can use these, with or without a venue of their own. They read the same public data a venue's website shows, and one of them books.

Tool What it does
guest_venues_search Finds venues that chose to be listed in the BookDinePlay app, by name or city, and returns each venue's slug
guest_venue_get Shows a venue's description, address, contact details, what can be booked, how long bookings last and the opening hours, including holidays
guest_menus_get Lists the published menus with dishes, drinks, prices and tags
guest_resources_get Lists the tables, billiard tables, dart boards, lanes and event areas with capacity and price
guest_availability Lists the free start times for a party on a date, with the tables free at each time; for a venue open past midnight, marks times after midnight (startsNextDay) and, with include_previous_night, adds the previous night's still-bookable tail (businessDate)
guest_specials Lists the specials of a day or of up to 14 days
guest_events Lists the published events
guest_voucher_offers Shows which gift vouchers the venue sells online
guest_create_booking Books a table or a game and sends the confirmation e-mail

Booking

guest_create_booking creates a real reservation, so the assistant should only call it after the guest has confirmed the venue, date, time, party size and contact details. The guest's name is an argument; the e-mail address is an argument too, and is taken from the sign-in when the account has one and the guest did not name a different one.

If the venue asks how many of a party are children, guest_create_booking takes an optional children number. The party size stays the total number of people, adults plus children, and at least one adult must remain. The assistant only sends it when the guest said so; a venue that switched the question off refuses a booking that states children.

The answer contains the booking reference, the status, the slot and the price estimate. It does not contain the link to manage or cancel the booking: that link is in the confirmation e-mail, and the assistant should tell the guest to use that e-mail to change or cancel. If the venue asks for a deposit, the booking stays Pending until the deposit is paid, and the assistant cannot take that payment: it is paid on the venue's booking page.

A guest can make at most 10 bookings an hour. To retry a booking after an error or a timeout without risking a second one, the assistant passes the same request_id again; the API then returns the original booking. A request_id belongs to the person who used it, so two people choosing the same value never meet.

What guests cannot do through an assistant

  • Look up, change or cancel an existing booking. Use the link in the confirmation e-mail.
  • Pay a deposit, register for an event, buy tickets or buy a voucher.
  • Read anything that is not public: other guests' bookings, a venue's guest list or its sales.

Operator tools

An operator's tools cover the console area by area. Each one calls the same API the console does, so what the console refuses, the tool refuses with the same message.

Area Tools
Account and terms server_info, whoami, legal_status, legal_accept, setup_progress, media_upload
Sign-up (no venue needed) onboarding_status, onboarding_check_slug, onboarding_legal_documents, onboarding_sign_up
Venues venues_list, venues_create, venue_create, venue_get, venue_update
Bookings reservations_today_overview, reservations_list, reservations_get, availability_check, reservations_create, reservations_update, reservations_set_status, reservations_refund_deposit, reservations_assign_table, reservation_requests_list, reservation_requests_approve, reservation_requests_decline
Opening hours hours_get, hours_replace, hours_add_closure, hours_set_special_day
Venue settings booking_durations_get, booking_durations_update, cancellation_policy_get, cancellation_policy_update, app_listing_get, app_listing_set, extras_get, extras_replace, booking_rules_get, booking_rules_update, children_settings_get, children_settings_set, allocation_settings_get, allocation_settings_update, child_rules_get, child_rules_update, high_chairs_get, high_chairs_set, unassigned_bookings_get, unassigned_bookings_set, request_settings_get, request_settings_set
Resources resources_list, resources_create, resources_update, resources_delete, resources_assign_group, resource_groups_list, resource_groups_create, resource_groups_update, resource_groups_delete, floor_plan_get, floor_plan_save, zones_create, zones_update, zones_delete, table_merges_list, table_merges_create, table_merges_update, table_merges_delete, resource_blocks_list, resource_blocks_create, resource_blocks_update, resource_blocks_delete
Menus and specials menus_get, menus_replace, menus_upsert_item, menus_remove_item, specials_list, specials_get, specials_days, specials_create, specials_update, specials_delete, specials_preview, specials_settings_get, specials_settings_update
Website highlights highlights_list, highlights_get, highlights_create, highlights_update, highlights_delete
Events events_list, events_get, events_create, events_update, events_publish, events_cancel, events_delete, events_preview, event_registrations_list, event_registrations_cancel, event_registrations_refund, event_checkin, event_undo_checkin
Vouchers voucher_settings_get, voucher_settings_update, vouchers_list, vouchers_get, vouchers_issue, vouchers_resend, vouchers_void, vouchers_change_expiry, vouchers_refund_sale, voucher_lookup, voucher_redeem, voucher_reverse_redemption
Orders, QR codes, messages orders_list, qr_codes_list, qr_codes_generate, qr_codes_regenerate, qr_codes_delete, messages_list, messages_reply
Stations and push notifications stations_list, stations_create, stations_update, stations_delete, station_routes_set, notification_preferences_get, notification_preferences_set
Team and API keys employees_list, employees_create, employees_set_active, employees_assign_resource, employees_unassign_resource, api_keys_list, api_keys_create, api_keys_revoke
Staff logins and shifts staff_list, staff_invite, staff_set_role, staff_link_employee, staff_remove, shifts_list, shifts_create, shifts_update, shifts_delete, staff_access_policy_get, staff_access_policy_set, staff_access_grants_list, staff_access_open, staff_access_revoke
No-show protection guest_blocks_list, guest_blocks_block, guest_blocks_unblock, guest_blocks_update_settings
Payouts and billing payouts_status, payouts_refresh, payouts_onboarding_link, billing_summary, billing_checkout_link, billing_portal_link, billing_update_company

Tools that replace a whole list, for example the menus or the weekly opening hours, say so in their description, and the assistant reads the current state first so that nothing you did not mention is lost. A tool that changes one thing, such as adding a closure, is preferred for a small change.

Accounts with several venues

On a Premium account with more than one venue, venues_list shows the venues with the slug of each. Every venue tool takes that slug as its venue argument, and the server sends it to the API exactly as the console does. Without a venue on an account with several, the tool refuses and names the venues to choose from; an account with one venue never needs the argument. Whether you may use a venue is decided by the API, so an operator limited to one venue is refused another one with the same message the console shows. venues_create adds a further venue within the plan limit (Premium, up to 25) and is for operators of the whole account only; venue_create creates the first one.

Platform admins

A platform admin also gets tools to list, create and update tenants (admin_tenants_list, admin_tenants_get, admin_tenants_create, admin_tenants_update), to list, add and correct a tenant's operators (admin_tenant_operators_list, admin_tenant_operators_create, admin_tenant_operators_update), to invite an operator by e-mail (admin_tenants_operators_invite), to resync billing (admin_billing_resync), to reset the demo venue (admin_demo_venue_reset) and to list and set the status of bookings across tenants (admin_reservations_list, admin_reservations_set_status). Every venue tool also accepts act_as_tenant for an admin who works inside one tenant. They appear only for an admin, and a call by anyone else is refused by the API itself.

admin_tenants_operators_invite creates the person's sign-in, links it to an operator of the tenant and sends them an e-mail with a link to set their password. Call it again for the same address and it sends the invite again; it never creates a second operator. If the address already belongs to an operator, or already signs in with Google, Apple or Microsoft, nothing is sent and the tool says what to do instead (admin_tenant_operators_create with the person's Auth0 subject). On their first sign-in the person must accept the terms of service and the data processing agreement before anything else works.

Confirming changes

Tools that are hard to undo, such as cancelling a booking, refunding a deposit, deleting a resource, voiding a voucher or regenerating a QR code, work in two steps. The first call changes nothing: it answers with a preview of exactly what would happen and a confirmation. The assistant shows you that preview. Only if you agree does it call the tool a second time with the confirmation, and only then does the change happen.

The confirmation is valid for five minutes, for you, for that tool and for exactly those arguments. If the assistant changes anything in the call, such as the booking or the amount, the confirmation no longer fits and it starts again with a new preview.

What operator tools never return

A secret API key is never shown in the chat: it is shown once on a page of its own outside the conversation. Voucher codes, ticket codes, QR token values and a guest's cancel link are never part of an answer either.

Setting up a new venue

A person without a venue can start from the assistant. The tools check where you are, check that the web address you want is free, show the terms of service and the data processing agreement and then sign you up.

  • You accept the terms yourself. The assistant never accepts on your behalf. Your client shows a form, and the acceptance is recorded only from your answer to that form. A client that cannot show such a form is sent to the web sign-up at app.bookdineplay.com instead.
  • You pay on Stripe's page. When a plan needs a payment, the assistant gives you a link to open yourself. Setup steps that need an active plan are refused until the payment has arrived.
  • Then it guides the setup step by step: profile and address, opening hours, tables and game resources, menu, booking rules and publishing. The prompt set_up_my_venue starts this, and the assistant can show what is already done and what is left.

Prompts

A prompt is a ready-made request your client can offer in a menu. It changes nothing by itself; the tools it names still work as described above.

Prompt What it asks the assistant to do
daily_briefing Summarise today at your venue: bookings, unpaid deposits and arrivals in the next hours, reading data only
set_holiday_hours Turn "closed on 24 December" into exact dates, show the bookings it affects and apply it after your confirmation
set_up_my_venue Run the guided setup above, one confirmed step at a time
admin_onboard_venue Platform admins: create a tenant for a new customer, invite their first operator by e-mail and explain the first sign-in

Limits

Each person may make 120 tool calls a minute, of which 30 may change data, and 10 guest bookings an hour. A call over the limit returns an error that says how long to wait.