MCP Integration

Astrocal provides a Model Context Protocol (MCP) server that lets AI agents manage scheduling — check availability, book meetings, cancel, reschedule, and list bookings. The MCP server is a thin wrapper around the REST API — it uses the same endpoints and business logic.

npm · GitHub

What is MCP?

The Model Context Protocol is an open standard for connecting AI agents to external tools and data sources. It lets language models call functions (tools) in a structured way.

Available Tools

The Astrocal MCP server exposes these tools:

Tool	Description
`list_event_types`	List available event types that can be booked
`check_availability`	Get available booking slots for a date range
`create_booking`	Book a meeting at a specific time
`cancel_booking`	Cancel an existing booking
`reschedule_booking`	Reschedule a booking to a new time
`list_bookings`	List bookings with optional status and event type filters

Setup

Install the MCP Server

npm install -g @astrocal/mcp-server

Or use npx to run without installing (recommended for Claude Desktop):

npx @astrocal/mcp-server

Configure Claude Desktop

Add Astrocal to your claude_desktop_config.json:

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

Restart Claude Desktop and the tools will be available.

Environment Variables

Variable	Required	Description
`ASTROCAL_API_KEY`	Yes	Your Astrocal API key (get from the dashboard)
`ASTROCAL_API_URL`	No	API base URL (default: `https://api.astrocal.dev`)
`ASTROCAL_DEFAULT_EVENT_TYPE_ID`	No	Default event type — skips needing to pass it to every tool

Tool Reference

`list_event_types`

List available event types that can be booked. No input required.

Returns each event type's ID, title, duration, and price (if paid).

`check_availability`

Check available time slots for a date range.

Parameter	Type	Required	Description
`event_type_id`	string	No	Event type to check (uses default if not set)
`start_date`	string	Yes	Start date (ISO 8601, e.g., `2026-03-15`)
`end_date`	string	Yes	End date (ISO 8601, e.g., `2026-03-22`)
`timezone`	string	No	IANA timezone (default: UTC)
`duration`	number	No	Duration in minutes — required for variable-duration event types

`create_booking`

Book a meeting at a specific time. Always check availability first.

Parameter	Type	Required	Description
`event_type_id`	string	No	Event type to book
`start_time`	string	Yes	ISO 8601 datetime
`invitee_name`	string	Yes	Full name of the invitee
`invitee_email`	string	Yes	Email for calendar invitation
`invitee_timezone`	string	No	IANA timezone (default: UTC)
`duration`	number	No	Duration in minutes — required for variable-duration event types
`notes`	string	No	Meeting notes (max 1000 chars)

`cancel_booking`

Cancel an existing booking. The invitee is notified via email. Idempotent — cancelling an already-cancelled booking returns success.

Parameter	Type	Required	Description
`booking_id`	string	Yes	ID of the booking to cancel
`reason`	string	No	Cancellation reason (max 500 chars)

`reschedule_booking`

Reschedule a booking to a new time. Check availability first using check_availability.

Parameter	Type	Required	Description
`booking_id`	string	Yes	ID of the booking to reschedule
`new_start_time`	string	Yes	New time in ISO 8601 format
`reason`	string	No	Reason for rescheduling (max 500)

`list_bookings`

List bookings with optional filters.

Parameter	Type	Required	Description
`status`	string	No	Filter: `confirmed`, `cancelled`, `pending_payment`
`limit`	number	No	Max results (default: 10, max: 100)
`event_type_id`	string	No	Filter by event type

Example Conversation

Once configured, an AI agent can manage scheduling naturally:

User: "What meetings can I book?"

Agent: calls list_event_types — "You have two event types: a 30-minute consultation (free) and a 1-hour strategy session ($50)."

User: "Schedule a 30-minute consultation with Jane for next Tuesday at 2pm"

Agent:

Calls check_availability to verify Tuesday 2pm is open

Calls create_booking with the invitee details

"Meeting confirmed for Tuesday at 2:00 PM UTC with Jane. A calendar invitation has been sent."

User: "Actually, move it to 3pm"

Agent: calls reschedule_booking — "Rescheduled to 3:00 PM. Jane has been notified."

User: "What bookings do I have this week?"

Agent: calls list_bookings — "You have 3 upcoming bookings..."

Next Steps

Quickstart — Set up the REST API first
React SDK — React provider, hooks, and widget component
Embeddable Widget — Drop-in booking widget for any website
API Reference — Full endpoint documentation

On this page