MCP tools reference

BookingKoala MCP tools

15 tools for BookingKoala on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server: https://cotlet.dev/mcp/v1
Connects with: Your BookingKoala admin or staff account
Integration page: BookingKoala

BookingKoala Endpoints
Endpoint	Access	Description
bookingkoala_list_bookings	read	Bookings with customer, services, date, arrival time, provider and price.
bookingkoala_get_booking	read	Full booking: services, address, provider, price and job length adjustments, notes and charges.
bookingkoala_list_customers	read	Customers with name, email, phone, addresses and number of bookings.
bookingkoala_list_providers	read	Providers and teams, active or not, with their bookings on a given day.
bookingkoala_list_charges	read	Booking charges with amount, status, card or cash/check, and refunds.
bookingkoala_list_invoices	read	Invoices from the Invoice Dashboard with customer, amount and due date.
bookingkoala_get_provider_payments	read	Amount due per provider for a pay period and amount owed up to today.
bookingkoala_create_booking	write	New booking for an existing or new customer, with a provider or left in the unassigned folder.
bookingkoala_reschedule_booking	write	Move a booking to a new date and arrival time.
bookingkoala_assign_provider	write	Assign a provider or team to a booking, or pair providers for it.
bookingkoala_add_booking_note	write	Add a private booking note, a private customer note or a note for the service provider.
bookingkoala_cancel_booking	write	Cancel a booking, with or without the cancellation fee and the provider's share of it.
bookingkoala_send_quote	write	Email a saved quote with an expiry date, reminder and optional offer.
bookingkoala_refund_charge	write	Full or partial refund of a charge. One refund per charge.
bookingkoala_resend_invoice	write	Resend an unpaid invoice to the customer.

List bookings

read

MCP tool bookingkoala_list_bookings

Lists bookings in one folder: upcoming, unassigned, drafts and quotes, or cancelled. Filter by date range, customer or provider. Pages follow the order of the folder; pass next_cursor back as cursor. Quotes in drafts_quotes carry the quote_id that send_quote needs.

Parameters

Parameters: list_bookings
Name	Type	Description
folder	enum	upcoming, unassigned, drafts_quotes or cancelled. Default: upcoming.
from	date	Only bookings on or after this date.
to	date	Only bookings on or before this date.
customer_id	string	Only bookings of this customer.
provider_id	string	Only bookings of this provider or team.
cursor	string	Next page cursor from the previous call.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_list_bookings",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_id": "48213",
        "customer": {
          "customer_id": "1207",
          "name": "Sarah Miller"
        },
        "services": [
          "Deep clean"
        ],
        "arrival": "2026-10-15T09:00:00-05:00",
        "provider": null,
        "folder": "unassigned",
        "price": "180.00"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get booking

read

MCP tool bookingkoala_get_booking

Returns one booking with its services, service address, assigned provider or team, price and job length adjustments, notes and charges. Use it before changing a booking so your agent sees its current state.

Parameters

Parameters: get_booking
Name	Type	Description
booking_id required	string	Booking ID from list_bookings.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_get_booking",
    "arguments": {
      "booking_id": "booking_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "48213",
    "customer": {
      "customer_id": "1207",
      "name": "Sarah Miller"
    },
    "services": [
      "Deep clean"
    ],
    "address": "14 Maple Street, Austin, TX",
    "arrival": "2026-10-15T09:00:00-05:00",
    "provider": {
      "id": "312",
      "name": "Team Blue"
    },
    "price": "180.00",
    "notes": [
      {
        "type": "private_booking",
        "text": "Gate code 4417"
      }
    ],
    "charges": [
      {
        "charge_id": "90417",
        "amount": "50.00",
        "status": "charged"
      }
    ]
  },
  "isError": false
}

List customers

read

MCP tool bookingkoala_list_customers

Lists customers, or searches them by name, email or phone. Each customer comes with addresses and a booking count. Use customer_id with list_bookings or create_booking. Pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_customers
Name	Type	Description
query	string	Search by name, email or phone.
limit	integer	Customers per page.
cursor	string	Next page cursor from the previous call.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_list_customers",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "customers": [
      {
        "customer_id": "1207",
        "name": "Sarah Miller",
        "email": "sarah@example.com",
        "phone": "+1 555 0100",
        "addresses": [
          "14 Maple Street, Austin, TX"
        ],
        "bookings": 6
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

List providers

read

MCP tool bookingkoala_list_providers

Lists providers and teams, active or not. Pass a date to see each provider's bookings that day, which shows who has room. Use the id as provider_id in list_bookings, create_booking and assign_provider.

Parameters

Parameters: list_providers
Name	Type	Description
date	date	Show each provider's bookings on this day.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_list_providers",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "providers": [
      {
        "id": "312",
        "name": "Team Blue",
        "type": "team",
        "active": true,
        "bookings_on_date": 3
      },
      {
        "id": "318",
        "name": "Marcus Reed",
        "type": "provider",
        "active": true,
        "bookings_on_date": 1
      }
    ]
  },
  "isError": false
}

List charges

read

MCP tool bookingkoala_list_charges

Lists charges from Booking Charges, newest first, with amount, status, payment method and any refund. Filter by booking or by charge date. The charge_id goes to refund_charge.

Parameters

Parameters: list_charges
Name	Type	Description
booking_id	string	Only charges of this booking.
from	date	Charged on or after this date.
to	date	Charged on or before this date.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_list_charges",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "charges": [
      {
        "charge_id": "90417",
        "booking_id": "48213",
        "amount": "50.00",
        "status": "charged",
        "method": "card",
        "charged_at": "2026-10-15T12:30:00-05:00",
        "refunded": "0.00"
      }
    ]
  },
  "isError": false
}

List invoices

read

MCP tool bookingkoala_list_invoices

Lists invoices from the Invoice Dashboard, the active ones or the ones on the Overdue tab. Each has customer, amount and due date. The invoice_id goes to resend_invoice.

Parameters

Parameters: list_invoices
Name	Type	Description
status	enum	active or overdue. Default: active.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_list_invoices",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoices": [
      {
        "invoice_id": "inv_7710",
        "customer": {
          "customer_id": "1207",
          "name": "Sarah Miller"
        },
        "amount": "240.00",
        "due_date": "2026-10-01",
        "status": "overdue"
      }
    ]
  },
  "isError": false
}

Get provider payments

read

MCP tool bookingkoala_get_provider_payments

Returns, per provider, the amount due for the pay period you give and the amount owed up to today, the same two figures as Provider Payments in BookingKoala. The amount owed up to today is never lower than the amount due for the period. It is read only: it does not pay anyone.

Parameters

Parameters: get_provider_payments
Name	Type	Description
from required	date	Start of the pay period.
to required	date	End of the pay period.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_get_provider_payments",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "from": "2026-09-28",
    "to": "2026-10-11",
    "providers": [
      {
        "id": "312",
        "name": "Team Blue",
        "amount_due": "1240.00",
        "owed_to_date": "1240.00"
      },
      {
        "id": "318",
        "name": "Marcus Reed",
        "amount_due": "610.00",
        "owed_to_date": "730.00"
      }
    ],
    "total_due": "1850.00"
  },
  "isError": false
}

Create booking

write Confirm

MCP tool bookingkoala_create_booking

Creates a booking for an existing customer, or for a new one when you pass a name and email. Without provider_id the booking waits in the unassigned folder. save_as can store it as a draft or a quote instead. Returns the booking_id and its folder. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: create_booking
Name	Type	Description
customer required	object	customer_id, or first_name, last_name and email for a new customer.
services required	object	Industry and the services or extras picked on the booking form.
arrival required	datetime	Date and arrival time, ISO 8601 with time zone.
address	string	Service address. Default: the customer's existing address.
provider_id	string	Provider or team. Omit to leave the booking unassigned.
payment	enum	existing_card or cash_check. Default: existing_card.
save_as	enum	booking, draft or quote. Default: booking.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_create_booking",
    "arguments": {
      "customer": {
        "customer_id": "1207"
      },
      "services": {
        "industry": "Home cleaning",
        "services": [
          "Deep clean"
        ]
      },
      "arrival": "2026-10-13T09:00:00-05:00",
      "payment": "existing_card",
      "save_as": "booking"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "48377",
    "status": "upcoming",
    "folder": "upcoming",
    "arrival": "2026-10-12T09:00:00-05:00",
    "customer": {
      "customer_id": "1207",
      "name": "Sarah Miller"
    },
    "provider": null,
    "payment": "cash_check"
  },
  "isError": false
}

Reschedule booking

write Confirm

MCP tool bookingkoala_reschedule_booking

Moves one booking to a new date and arrival time and returns the updated booking. The assigned provider or team stays unless keep_provider is false. Rescheduling fees are set in BookingKoala; check them before moving many jobs. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reschedule_booking
Name	Type	Description
booking_id required	string	Booking ID from list_bookings.
arrival required	datetime	New date and arrival time, ISO 8601 with time zone.
keep_provider	boolean	Keep the assigned provider or team. Default: true.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_reschedule_booking",
    "arguments": {
      "booking_id": "48213",
      "arrival": "2026-10-16T10:00:00-05:00",
      "keep_provider": true
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "48213",
    "status": "upcoming",
    "arrival": "2026-10-16T10:00:00-05:00",
    "provider": {
      "id": "312",
      "name": "Team Blue"
    }
  },
  "isError": false
}

Assign provider

write Confirm

MCP tool bookingkoala_assign_provider

Assigns one provider or team to a booking, which takes it out of the unassigned folder. Pass several provider_ids to pair providers on one booking; that needs provider pairing switched on in your BookingKoala scheduling permissions and on each provider. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: assign_provider
Name	Type	Description
booking_id required	string	Booking ID from list_bookings.
provider_ids required	string[]	One provider or team, or several providers to pair.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_assign_provider",
    "arguments": {
      "booking_id": "48213",
      "provider_ids": [
        "312"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "48213",
    "status": "assigned",
    "folder": "upcoming",
    "providers": [
      {
        "id": "312",
        "name": "Team Blue"
      }
    ]
  },
  "isError": false
}

Add booking note

write Confirm

MCP tool bookingkoala_add_booking_note

Adds a note to a booking. private_booking and private_customer notes are for your team only; for_provider is shown to the service provider, so it reaches another person. Returns the note_id. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: add_booking_note
Name	Type	Description
booking_id required	string	Booking ID from list_bookings.
type required	enum	private_booking, private_customer or for_provider.
text required	string	Note text.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_add_booking_note",
    "arguments": {
      "booking_id": "booking_8c41d2",
      "type": "private_booking",
      "text": "text"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "note_id": "n_5521",
    "booking_id": "48213",
    "type": "for_provider",
    "status": "added"
  },
  "isError": false
}

Cancel booking

write Confirm

MCP tool bookingkoala_cancel_booking

Cancels one booking and moves it to the cancelled folder. charge_fee false cancels without your cancellation fee. pay_provider false skips the provider's share of the fee. reason takes one of the cancellation reasons you set up in BookingKoala. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: cancel_booking
Name	Type	Description
booking_id required	string	Booking ID from list_bookings.
charge_fee	boolean	Charge your cancellation fee. Default: true.
pay_provider	boolean	Pay the provider out of the fee. Default: true.
reason	string	One of your cancellation reasons, if set up.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_cancel_booking",
    "arguments": {
      "booking_id": "booking_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_id": "48213",
    "status": "cancelled",
    "folder": "cancelled",
    "fee_charged": false,
    "reason": "Customer request"
  },
  "isError": false
}

Send quote

write Confirm

MCP tool bookingkoala_send_quote

Emails a quote saved in the drafts and quotes folder to the customer, with an optional expiry date, reminder and offer. Returns the recipient and expiry. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_quote
Name	Type	Description
quote_id required	string	Quote ID from list_bookings with folder drafts_quotes.
to	string	Recipient email. Default: the customer's email.
expires_on	date	Expiry date of the quote link.
reminder_days	integer	Send a reminder after this many days.
offer	string	Discount, e.g. "10%" or "$20".

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_send_quote",
    "arguments": {
      "quote_id": "quote_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "quote_id": "q_3302",
    "status": "sent",
    "to": "sarah@example.com",
    "expires_on": "2026-10-25"
  },
  "isError": false
}

Refund charge

write Confirm

MCP tool bookingkoala_refund_charge

Refunds a charge in full, or in part when you pass amount; a partial amount includes tax. BookingKoala allows one refund per transaction, so a second refund on the same charge fails. The reason shows on the booking. notify false skips the customer notification. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: refund_charge
Name	Type	Description
charge_id required	string	Charge ID from list_charges.
amount	string	Partial refund including tax. Omit for a full refund.
reason required	string	Reason shown on the booking.
notify	boolean	Notify the customer. Default: true.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_refund_charge",
    "arguments": {
      "charge_id": "charge_8c41d2",
      "reason": "reason"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "charge_id": "90417",
    "status": "refunded",
    "charge_amount": "50.00",
    "refunded": "25.00",
    "reason": "Kitchen not finished, half refunded"
  },
  "isError": false
}

Resend invoice

write Confirm

MCP tool bookingkoala_resend_invoice

Resends one unpaid invoice to its customer, the same as Resend in the Actions menu of the Invoice Dashboard. Returns the send time. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: resend_invoice
Name	Type	Description
invoice_id required	string	Invoice ID from list_invoices.

tools/call

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bookingkoala_resend_invoice",
    "arguments": {
      "invoice_id": "invoice_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoice_id": "inv_7710",
    "status": "resent",
    "to": "sarah@example.com",
    "sent_at": "2026-10-12T08:00:00-05:00"
  },
  "isError": false
}

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Parameters

tools/call

Example response

Analytics cookies