Documentation

CalMesh API reference and MCP server setup guide.

Quick Start

Sign up at calmesh.xyz and connect your calendars
Generate a scoped API key in Dashboard → API Keys
Call the API or install the MCP server:

# Check availability via REST API
curl "https://calmesh.xyz/api/v1/calendars/work/availability?date=2026-03-15" \
  -H "Authorization: Bearer cm_live_..."

# Or use the MCP server
CALMESH_API_KEY=cm_live_... npx @calmesh/mcp-server

Authentication

All authenticated endpoints accept a Bearer token in the Authorization header. API keys start with cm_live_ and have one of four scopes. Scopes are capabilities, not a hierarchy — book does not grant write access, and vice versa:

Scope	Permissions
read	List calendars, query events, check availability, detect conflicts
write	read + create/update/delete calendar events
book	read + create/cancel bookings, manage polls
full	All capabilities: events, bookings, connections, calendars, webhooks, API keys

Using CalMesh with AI Assistants

Two ways to connect: REST API (works everywhere) or MCP server (Claude Desktop, Cursor, Windsurf).

REST API

ChatGPT, Claude.ai, Gemini, and custom agents can call the CalMesh API directly via function calling. Give your AI the base URL and API key — it handles the rest.

curl "https://calmesh.xyz/api/v1/calendars/work/availability?date=2026-03-15" \
  -H "Authorization: Bearer cm_live_..."

Full endpoint list: API Reference

MCP Server

19 calendar tools via Model Context Protocol. Tools appear in your AI's tool palette automatically.

Works with: Claude Desktop, Claude Code, Cursor, Windsurf. Not supported: Claude.ai web, ChatGPT — use the REST API.

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": { "CALMESH_API_KEY": "cm_live_your_key_here" }
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": { "CALMESH_API_KEY": "cm_live_your_key_here" }
    }
  }
}

Windsurf

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": { "CALMESH_API_KEY": "cm_live_your_key_here" }
    }
  }
}

HTTP Transport

CALMESH_API_KEY=cm_live_... \
CALMESH_HTTP_SECRET=your_secret \
npx @calmesh/mcp-server --transport http --port 3100

Available Tools

Core (read scope)

Tool	Description
calmesh_list_calendars	List all unified calendars
calmesh_get_events	Get events within a date range
calmesh_check_availability	Check available time slots
calmesh_find_conflicts	Find overlapping events

Booking (book scope)

Tool	Description
calmesh_get_slots	Get available booking slots
calmesh_create_booking	Create a new booking
calmesh_cancel_booking	Cancel a booking
calmesh_list_bookings	List bookings with pagination

Poll (book for create/decide, read for list/overlap)

Tool	Description
calmesh_create_poll	Create a scheduling poll
calmesh_list_polls	List all polls
calmesh_get_poll_overlap	Get participant overlap
calmesh_decide_poll	Finalize poll with chosen time

Setup (full scope)

Tool	Description
calmesh_start_oauth_connection	Connect Google or Microsoft calendar
calmesh_start_credential_connection	Connect CalDAV or iCal URL
calmesh_check_connection_status	Check connection sync status
calmesh_list_connections	List all connections
calmesh_remove_connection	Remove a connection
calmesh_create_calendar	Create unified calendar with sources
calmesh_manage_calendar	Update calendar, manage sources

API Reference

Base URL: https://calmesh.xyz/api/v1 · OpenAPI spec (JSON)

38 endpoints across 8 categories.

API Keys

POST

/api/v1/api-keys

Create a new API key (returns the full key once)

auth: session

GET

/api/v1/api-keys

List all API keys (prefix and metadata only)

auth: session

DELETE

/api/v1/api-keys/:id

Revoke an API key

auth: session

Calendar Connections

GET

/api/v1/connections

List all calendar connections for the authenticated user

auth: session/key

POST

/api/v1/connections/google

Initiate Google Calendar OAuth flow

auth: session

POST

/api/v1/connections/microsoft

Initiate Microsoft Outlook/365 OAuth flow

auth: session

POST

/api/v1/connections/icloud

Connect Apple iCloud Calendar via CalDAV

auth: session

GET

/api/v1/connections/:id

Get connection details and status

auth: session/key

DELETE

/api/v1/connections/:id

Disconnect a calendar (deletes connection and cached events)

auth: session/key

POST

/api/v1/connections/:id/sync

Trigger a manual sync for a connection

auth: session/key

Unified Calendars

POST

/api/v1/calendars

Create a unified calendar

auth: session/key

GET

/api/v1/calendars

List all unified calendars

auth: session/key

GET

/api/v1/calendars/:slug

Get unified calendar details

auth: session/key

PATCH

/api/v1/calendars/:slug

Update a unified calendar

auth: session/key

DELETE

/api/v1/calendars/:slug

Delete a unified calendar

auth: session/key

POST

/api/v1/calendars/:slug/sources

Add a connection to a unified calendar

auth: session/key

PATCH

/api/v1/calendars/:slug/sources/reorder

Reorder sources within a unified calendar (sort_order determines default write target)

auth: session

DELETE

/api/v1/calendars/:slug/sources/:sourceId

Remove a connection from a unified calendar

auth: session/key

POST

/api/v1/calendars/:slug/events

Create an event on a connected calendar (for AI agents/MCP)

auth: session/key

DELETE

/api/v1/calendars/:slug/events

Delete an event from a connected calendar

auth: session/key

GET

/api/v1/calendars/:slug/events

Query merged events from all sources in a unified calendar

auth: session/key

GET

/api/v1/calendars/:slug/availability

Query free/busy availability for a unified calendar

auth: session/key

GET

/api/v1/calendars/:slug/conflicts

Detect overlapping events across different sources

auth: session/key

Booking Pages

POST

/api/v1/booking-pages

Create a booking page attached to a unified calendar

auth: session/key

GET

/api/v1/booking-pages

List all booking pages

auth: session/key

GET

/api/v1/booking-pages/:slug

Get booking page configuration

auth: session/key

PATCH

/api/v1/booking-pages/:slug

Update a booking page

auth: session/key

DELETE

/api/v1/booking-pages/:slug

Delete a booking page

auth: session/key

GET

/api/v1/booking-pages/:slug/slots

Get available booking slots (public)

POST

/api/v1/booking-pages/:slug/book

Create a booking (public, visitor submits)

Bookings

GET

/api/v1/bookings

List bookings for the authenticated user

auth: session/key

GET

/api/v1/bookings/:id

Get booking details

auth: session/key

PATCH

/api/v1/bookings/:id/cancel

Cancel a booking (HMAC signature for visitors, auth for owner)

Billing

GET

/api/v1/billing

Get current subscription status

auth: session

POST

/api/v1/billing/subscribe

Initiate Mollie first payment for subscription

auth: session

POST

/api/v1/billing/cancel

Cancel active subscription

auth: session

User

GET

/api/v1/me

Get current user profile

auth: session/key

System

GET

/api/health

Health check endpoint

Embeddable Widget

Embed a CalMesh booking page on any website. Supports inline (iframe) and popup (modal) modes.

Inline Mode

<div
  data-calmesh-handle="your-handle"
  data-calmesh-slug="your-booking-page"
  data-mode="inline"
></div>
<script src="https://calmesh.xyz/embed.js" defer></script>

Popup Mode

<div
  data-calmesh-handle="your-handle"
  data-calmesh-slug="your-booking-page"
  data-mode="popup"
  data-color="#f97316"
></div>
<script src="https://calmesh.xyz/embed.js" defer></script>