Developer docs menu
Reference
MCP tools
Every tool the MCP server offers an AI assistant. This page is drawn from the server’s own tool list.
Server address: https://api.bookingmachine.io/v1/mcp. To connect, see MCP server.
get_business_profile
Reads onlyBusiness profile
Who a business is: name, contact details, opening hours, timezone, currency, booking rules, rating, and what can be done for it right now (capabilities). Start here.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
list_services
Reads onlyServices on sale
The business’s services with their length and base price. Never tell a customer basePrice as the price: their answers change it, so use calculate_quote.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
get_service_requirements
Reads onlyWhat a service needs to know
The questions that set a service’s price (dimensions), its other questions, its add-ons, and whether an address, payment or signed documents are needed. Ask the customer these before calculate_quote.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| serviceId | string | Required. A service id from list_services. |
| with | array of string | Other service ids booked with it. |
calculate_quote
Reads onlyThe real price
The price for what the customer wants, worked out by the business’s own pricing rules exactly as its booking form does. Saves nothing and tells nobody, so call it again whenever an answer changes. If something is missing the error lists what still has to be asked.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| serviceIds | array of string (uuid) | Required. up to 20 items |
| answers | object | |
| addons | array of string | up to 50 items |
| date | string | |
| checkInDate | string | |
| checkOutDate | string | |
| hours | integer | 1 to 24 |
| recurringFrequency | "weekly" | "biweekly" | "monthly" | |
| voucherCode | string | up to 32 characters |
check_availability
Reads onlyFree times
The times a customer can book, each with an id to hold or book it with (good for 24 hours). Give date for one day, or from and to for up to 7 days. start and end are UTC; tell the customer the time on the business’s own clock (timezone).
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| serviceId | string | Required. A service id from list_services. |
| with | array of string | Other service ids booked with it. |
| date | string | One day, as the business counts days (YYYY-MM-DD). |
| from | string | The first day of a range. |
| to | string | The last day of a range. |
| addons | array of string | Add-on keys: they lengthen the job. |
| hours | integer | For a service sold by the hour. 1 to 24 |
hold_slot
Changes somethingHold a time
Keep a free time for a few minutes (10 unless said, 15 at most) while the customer decides, so nobody else takes it. Put the holdToken on create_booking.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| slotId | string | Required. up to 1024 characters |
| ttlMinutes | integer | 1 to 15 |
| idempotencyKey | string | A value of your own, unique to this attempt. Send the same one when retrying and the first answer comes back instead of a second booking. |
release_hold
Changes somethingLet a held time go
Give a held time back before it runs out, when the customer has decided against it.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| holdToken | string | Required. The holdToken from hold_slot. |
create_booking
Changes somethingBook for a customer
Ask for a booking for a named customer. Only do this once the customer has agreed the price and the time. Without an API key nothing is booked yet: the customer is emailed a link and the booking is made when they confirm, so tell them to check their email (status is awaiting_customer_confirmation, and get_booking shows when it changes). If the business takes payment or signed documents at booking, the error gives the booking page address to send the customer to instead.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| serviceIds | array of string (uuid) | Required. up to 10 items |
| slotId | string | up to 1024 characters |
| holdToken | string | up to 128 characters |
| answers | object | |
| addons | array of string | up to 50 items |
| hours | integer | 1 to 24 |
| recurringFrequency | "weekly" | "biweekly" | "monthly" | |
| voucherCode | string | up to 32 characters |
| customer | object | Required. |
| notes | string | up to 2000 characters |
| idempotencyKey | string | A value of your own, unique to this attempt. Send the same one when retrying and the first answer comes back instead of a second booking. |
get_booking
Reads onlyA booking’s status
Whether a booking asked for with create_booking has been confirmed by the customer, has lapsed, or was made.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| id | string | Required. The id create_booking answered with. |
list_reviews
Reads onlyCustomer reviews
The reviews the business publishes, the newest first, with its average rating.
| Field | Type | Notes |
|---|---|---|
| business | string | Required. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself. |
| limit | integer | How many; 10 unless said. 1 to 20 |
| cursor | string | nextCursor from the page before, for more. |
list_my_businesses
Reads onlyBusinesses this partner set up
Partner key only. The businesses this partner has made, the newest first, each with whether its real owner has taken it over.
Nothing to send.
provision_business
Changes somethingSet up a business
Partner key only. Make a new business with its opening hours and services. It is a Free business owned by the partner’s account until its real owner takes it over; nobody is emailed and payments stay off.
| Field | Type | Notes |
|---|---|---|
| name | string | Required. up to 255 characters |
| slug | string | Required. up to 100 characters |
| vertical | string | up to 100 characters |
| string (email) | up to 255 characters | |
| phone | string | up to 50 characters |
| timezone | string | Required. |
| currency | string | Required. up to 3 characters |
| country | string | |
| locale | string | up to 35 characters |
| hours | array of object | up to 7 items |
| services | array of object | up to 50 items |
| starterServices | boolean | |
| idempotencyKey | string | A value of your own, unique to this attempt. Send the same one when retrying and the first answer comes back instead of a second booking. |