CalFree
Create your page
Browse documentation

MCP server

A Model Context Protocol server so an AI agent can read your availability and manage bookings, using the same handlers and the same rules as the booking page.

Connecting

The server is stateless streamable HTTP at /mcp, authenticated with the same API keys as the REST API. Create one in Settings → API keys, then point your client at it:

{
  "mcpServers": {
    "calfree": {
      "type": "http",
      "url": "https://calfree.dev/mcp",
      "headers": { "Authorization": "Bearer cf_live_..." }
    }
  }
}

Being stateless and HTTP means there is no local process to install and no session to keep alive — a request carries its own authentication, and any client that speaks streamable HTTP can use it.

Tools

Seven tools. Each one calls the handler of its REST twin, so results are identical to the equivalent API call, and a booking an agent makes sends the same emails and writes the same calendar event as one made on the page.

  • list_event_typesread only

    Every event type with its id, title and duration. The first call in any flow.

  • list_slotsread only

    Open start times between two dates, as ISO 8601 with offset. Group events also report spots left.

  • create_bookingwrites

    Takes a slot and the invitee's details. Sends the emails and writes the calendar event.

  • list_bookingsread only

    Bookings soonest first, filterable by status and start time. Use it to find a booking id.

  • cancel_bookingwrites

    Frees the slot and tells the invitee why.

  • reschedule_bookingwrites

    Moves a booking to a new start time and notifies the invitee.

  • get_availabilityread only

    The weekly hours and date overrides behind the slots.

The order to call them in

Tool descriptions say what to call first, so a capable agent usually works it out unaided. The path through is:

  1. list_event_types for an event_type_id.
  2. list_slots for that id and a date range, which returns ISO 8601 start times with offsets.
  3. create_booking with a start time passed back unchanged, plus the invitee’s name and email.

To change an existing meeting, list_bookings gives you a booking_id for reschedule_booking or cancel_booking. Use list_slots rather than get_availability to find times that are actually free: availability describes your weekly hours, while slots account for existing bookings, buffers, notice, caps and calendar busy time.

Errors

Errors come back as plain-language messages that say which tool to call next, because that is what an agent can act on. A slot taken between listing and booking, for instance, tells the agent to call list_slots again rather than returning slot_unavailable and leaving it to guess.

Limits and auditing

  • Rate limit: 300 requests a minute per key, shared with REST calls using that key.
  • Scope: a key acts as you and reaches only your own data. There is no narrower scope than that yet, so give each agent its own key.
  • Audit: bookings made through MCP are recorded with created_via: mcp, so you can always tell which of your meetings an agent arranged.
  • Revocation: deleting a key in Settings → API keys cuts the agent off immediately, without touching your booking page.

What it cannot do

The tools cover event types, slots, bookings and availability. An agent cannot change your settings, create API keys, connect a calendar or read another host’s data. Writing availability is a REST call, not a tool.