iCalendly MCP Server v2 Integration Guide

Bottom Line Up Front: iCalendly provides a dedicated Model Context Protocol (MCP) server hosted at mcp.icalendly.com. It acts as a stateless, highly optimized bridge to our API v2. It uses SSE transport for cloud clients (Claude.ai) and the mcp-remote bridge for local clients (Claude Desktop). All responses complete in <500ms.

1. Quickstart Integration

Claude.ai (Web)

To connect your Claude.ai account to the live iCalendly MCP server:

Go to Customize > Connectors.
Add a custom connector and point it to the public endpoint: https://mcp.icalendly.com/mcp
Under Advanced settings, configure your Authorization headers:
- Header: Authorization
- Value: Bearer YOUR_API_KEY (Generate this under Settings > Developer > API Keys)

Claude Desktop (Local)

To connect your local Claude Desktop app, edit your configuration file (accessible via Settings > Developer > Edit Config):

{
  "mcpServers": {
    "icalendly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.icalendly.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop to apply the changes.

2. Tool Capabilities

The MCP server exposes 7 core tools designed to manage the booking lifecycle:

Tool Name	Purpose	Required Context
`get_profile`	Returns user profile details (username, name, email, timezone).	None. Call first to obtain `username`.
`list_event_types`	Lists all configured event types (ID, slug, title, duration).	None. Call before booking.
`get_available_slots`	Returns available time slots within a date range.	`startTime`, `endTime`, plus either `eventTypeId` OR `eventTypeSlug` + `username`.
`create_booking`	Books a meeting slot. Triggers sync and rooms.	`start`, `attendee` object, plus either `eventTypeId` OR `eventTypeSlug` + `username`.
`retrieve_booking`	Retrieves booking details by UID or lists filtered bookings.	`bookingUid` (optional), `status` (optional).
`reschedule_booking`	Moves an existing booking to a new time slot.	`bookingUid`, new `start` time.
`cancel_booking`	Permanently cancels a booking.	`bookingUid`, `cancellationReason` (required).

3. Error Codes & Self-Correction

All API v2 errors mapped through the MCP proxy are enriched to provide self-correcting instructions:

409 Conflict ("Time Slot Unavailable"): The requested time slot is already booked. Immediately call get_available_slots to locate open slots.
401 Unauthorized ("Authentication Failed"): The provided API key is invalid or expired. Re-verify settings.
404 Not Found ("Booking Not Found"): The specified booking UID does not exist. Call retrieve_booking without a UID to list active bookings and locate the correct UID.
422 Unprocessable Entity ("Missing Required Field"): An operation-critical parameter (e.g., cancellationReason for cancel_booking) was omitted.