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 only

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

FieldTypeNotes
businessstringRequired. 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 only

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

FieldTypeNotes
businessstringRequired. 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 only

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

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
serviceIdstringRequired. A service id from list_services.
witharray of stringOther service ids booked with it.

calculate_quote

Reads only

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

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
serviceIdsarray of string (uuid)Required. up to 20 items
answersobject
addonsarray of stringup to 50 items
datestring
checkInDatestring
checkOutDatestring
hoursinteger1 to 24
recurringFrequency"weekly" | "biweekly" | "monthly"
voucherCodestringup to 32 characters

check_availability

Reads only

Free 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).

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
serviceIdstringRequired. A service id from list_services.
witharray of stringOther service ids booked with it.
datestringOne day, as the business counts days (YYYY-MM-DD).
fromstringThe first day of a range.
tostringThe last day of a range.
addonsarray of stringAdd-on keys: they lengthen the job.
hoursintegerFor a service sold by the hour. 1 to 24

hold_slot

Changes something

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

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
slotIdstringRequired. up to 1024 characters
ttlMinutesinteger1 to 15
idempotencyKeystringA 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 something

Let a held time go

Give a held time back before it runs out, when the customer has decided against it.

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
holdTokenstringRequired. The holdToken from hold_slot.

create_booking

Changes something

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

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
serviceIdsarray of string (uuid)Required. up to 10 items
slotIdstringup to 1024 characters
holdTokenstringup to 128 characters
answersobject
addonsarray of stringup to 50 items
hoursinteger1 to 24
recurringFrequency"weekly" | "biweekly" | "monthly"
voucherCodestringup to 32 characters
customerobjectRequired.
notesstringup to 2000 characters
idempotencyKeystringA 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 only

A booking’s status

Whether a booking asked for with create_booking has been confirmed by the customer, has lapsed, or was made.

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
idstringRequired. The id create_booking answered with.

list_reviews

Reads only

Customer reviews

The reviews the business publishes, the newest first, with its average rating.

FieldTypeNotes
businessstringRequired. The business: its slug (the last part of its booking page address, e.g. "sparkle-cleaning") or the booking page address itself.
limitintegerHow many; 10 unless said. 1 to 20
cursorstringnextCursor from the page before, for more.

list_my_businesses

Reads only

Businesses 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 something

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

FieldTypeNotes
namestringRequired. up to 255 characters
slugstringRequired. up to 100 characters
verticalstringup to 100 characters
emailstring (email)up to 255 characters
phonestringup to 50 characters
timezonestringRequired.
currencystringRequired. up to 3 characters
countrystring
localestringup to 35 characters
hoursarray of objectup to 7 items
servicesarray of objectup to 50 items
starterServicesboolean
idempotencyKeystringA 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.