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.

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)

`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)
`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
API Reference — Full endpoint documentation

On this page