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 that 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
`join_waitlist`	Add an invitee to the waitlist for a fully-booked event type
`check_waitlist`	Check waitlist position for an invitee

Setup

There are two ways to connect, both available from the AI Tools screen in your dashboard.

Recommended: remote connector (OAuth)

Add Astrocal as a custom connector — no install and no API key. Paste the connector URL into your AI tool and sign in:

https://api.astrocal.dev/mcp

The tool registers itself automatically (Dynamic Client Registration), you approve the requested permissions on a consent screen, and access is granted via OAuth 2.1. This works in Claude (web, desktop, mobile), ChatGPT, and Cursor — anywhere that supports remote MCP servers. You can review and revoke connected apps anytime from the AI Tools page. See the remote connector guide for details.

Alternative: local server (API key)

Prefer to run the server locally? The npm package authenticates with an API key. The connect screen creates a key and fills in a ready-to-paste snippet — or a one-click install link — for your specific tool. Your raw key is shown only once.

Per-tool setup guides, each with the exact config file path and snippet:

Claude Desktop — one-click .mcpb bundle or claude_desktop_config.json
Claude Code — a single claude mcp add command
Cursor — "Add to Cursor" deeplink or .cursor/mcp.json
Windsurf — ~/.codeium/windsurf/mcp_config.json
VS Code — "Install in VS Code" deeplink or .vscode/mcp.json

All clients run the published @astrocal/mcp-server package via npx — no global install required. The canonical config is:

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

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

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