Build an AI Booking Agent with MCP: A Step-by-Step Tutorial

Most "AI scheduling" stops at suggesting a time and waiting for a human to click confirm. This tutorial goes the whole way: an AI agent that checks real availability and creates a confirmed booking by itself, using the Model Context Protocol (MCP) and the Astrocal MCP server.

It takes about 10 minutes and requires no application code — MCP does the wiring for you. If you've never used MCP before, that's fine; we'll set it up from scratch.

What you'll build

An AI assistant that can hold a conversation like "Book me a 30-minute intro call with jordan@example.com sometime Tuesday afternoon" and actually make it happen — picking a free slot from your real calendar, creating the booking, and sending the confirmation. The same setup also lets the agent cancel and reschedule.

Under the hood, the Astrocal MCP server exposes 8 tools the model can call: check_availability, create_booking, cancel_booking, reschedule_booking, list_bookings, list_event_types, join_waitlist, and check_waitlist. The model decides which to call and when — you just describe what you want.

Prerequisites

• An MCP client — Claude Desktop, Cursor, Windsurf, or any MCP-compatible runtime. We'll use Claude Desktop as the main example.
• Node.js 18+ — the server runs via npx, so there's nothing to clone or build.
• An Astrocal account — free, no credit card. We'll create one in Step 1.

Step 1: Get an API key

Create a free account and generate an API key from the dashboard. Keys are prefixed by environment:

• ac_test_… — sandbox. No real calendar events, emails, or charges. Use this while building.
• ac_live_… — production.

Start with a ac_test_ key. Copy it somewhere safe — you'll paste it into your MCP client's config next.

Step 2: Create a bookable event type

An event type is the thing people book — its duration, availability window, and (optionally) price. Create one in the dashboard (for example, a 30-minute "Intro call") and connect a Google, Outlook, or CalDAV calendar so availability reflects your real schedule.

Note the event type's ID. You can pass it on each tool call, or set it once as a default so your agent never has to specify it:

ASTROCAL_DEFAULT_EVENT_TYPE_ID=evt_01abc...

Step 3: Connect the MCP server

Add Astrocal to your client's MCP configuration. The server is published on npm as @astrocal/mcp-server and runs with npx — no install step.

{
"mcpServers": {
  "astrocal": {
    "command": "npx",
    "args": ["-y", "@astrocal/mcp-server"],
    "env": {
      "ASTROCAL_API_KEY": "ac_test_xxxxxxxxxxxxx",
      "ASTROCAL_DEFAULT_EVENT_TYPE_ID": "evt_01abc..."
    }
  }
}
}

The only required variable is ASTROCAL_API_KEY. Restart the client and the eight scheduling tools become available immediately. In Claude Desktop you'll see them listed under the tools (hammer) icon.

Step 4: Let the agent book

Now just talk to it. A first message to confirm the connection:

You: What event types can I book?

Agent: (calls list_event_types) You have one: "Intro call" — 30 minutes.

Then the real thing:

You: Find a 30-minute slot next Tuesday afternoon and book it for Jordan Lee (jordan@example.com).

Agent: (calls check_availability for Tuesday, then create_booking with the chosen start_time, invitee_name, and invitee_email) Booked Jordan Lee for Tuesday at 2:00 PM. A confirmation email is on its way.

That's the whole loop — availability check, slot selection, confirmed booking — with no human clicking through a UI. Because the model is calling a real scheduling API, the booking lands on your connected calendar and follows the rules you set (buffers, limits, working hours). Cancellations and reschedules work the same way: give the agent the booking ID and it calls cancel_booking or reschedule_booking.

If the agent tries a slot that was just taken, the API returns a 409 Conflict; a well-prompted agent simply re-checks availability and picks another time. (Astrocal also enforces a database-level constraint so two agents can never double-book the same slot.)

Step 5: Test safely with sandbox mode

Because you used an ac_test_ key, everything above ran in sandbox mode: bookings are created in the API so the agent's flow is real, but no calendar events are written, no emails are sent, and no payments are charged. Iterate on your prompts and event-type config freely. When you're ready, swap the key for an ac_live_… one and restart the client — nothing else changes.

Beyond Claude: custom agents

MCP isn't limited to desktop assistants. The Astrocal MCP server speaks standard stdio MCP, so any MCP-compatible agent runtime can load it the same way — point your framework's MCP client at npx -y @astrocal/mcp-server with the ASTROCAL_API_KEY env var, and the eight tools appear in the model's toolset.

If your stack doesn't speak MCP, you don't lose anything: the MCP server is a thin wrapper over the Astrocal REST API, so you can call the same endpoints directly. The API quickstart walks through creating a booking with a single POST request.