WhenMeet.me for developers & AI agents

Everything the WhenMeet.me UI does is available programmatically: a documented HTTP API and a remote MCP server, both on this origin. Machine-readable spec: /openapi.json (OpenAPI 3.1). LLM-friendly product summary: /llms.txt.

MCP server (recommended for AI agents)

Remote MCP server (Streamable HTTP, stateless JSON responses, protocol versions 2025-06-18, 2025-03-26 and 2024-11-05) at:

https://whenmeet.me/mcp

Claude.ai and ChatGPT (OAuth connector)

Add https://whenmeet.me/mcp as a custom connector — Claude.ai: Settings → Connectors → Add custom connector; ChatGPT: Settings → Connectors → Create (developer mode) with authentication OAuth. The client registers itself (Dynamic Client Registration), sends you to WhenMeet.me to sign in and approve, and receives tokens bound to /mcp. Disconnect any time in Settings → Connected apps. Full guide: MCP for AI agents.

Claude Code, Cursor and scripts (token header)

« Claude Code »
claude mcp add --transport http whenmeet https://whenmeet.me/mcp \
  --header "Authorization: Bearer $WHENMEET_TOKEN"

Create the token in Settings → API tokens & MCP.

Tools

15 tools. Every /mcp request needs a token (OAuth or a personal access token) — there is no anonymous use. Tools with scope write change data and need a token with the write scope (a read-only token gets an insufficient_scope tool error). Every tool carries MCP annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint), an outputSchema and returns structuredContent.

A request without credentials (including initialize and tools/list) gets HTTP 401 with WWW-Authenticate: Bearer resource_metadata="https://whenmeet.me/.well-known/oauth-protected-resource/mcp", which starts the OAuth flow in connectors. A token that is malformed, unknown, revoked or expired gets HTTP 401 with JSON-RPC error -32001 invalid_token and WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://whenmeet.me/.well-known/oauth-protected-resource/mcp" — never a silent anonymous call. Server card: /.well-known/mcp.json.

OAuth 2.1 endpoints

Authentication for agents

1. Sign in at WhenMeet.me with Google or Microsoft (one-time, human step; the account’s email address must be verified by the provider).
2. Create a personal access token in Settings → API tokens & MCP (or POST /api/tokens with your browser session, body { name?, scopes?: ["read"] | ["read","write"], expiresInDays?: 30 | 90 | 365 | null }); the plaintext mn_… token is shown once.
3. Send it on API and MCP calls: Authorization: Bearer mn_…

Scopes: read covers read-only tools and GET endpoints (plus the read-only slot/ranking POSTs); write adds creating, cancelling and rescheduling meetings and bookings, marking availability and every other change. A call outside the token’s scope gets 403 insufficient_scope. New tokens expire after 90 days by default (30 / 90 / 365 days or never); an expired token gets 401 invalid_token. Tokens created before scopes existed keep full access and never expire. Revoke any time with DELETE /api/tokens/:id. On the HTTP API, guest-side actions (reading a meeting, suggesting times, marking availability) need no token — the share-link UUID or the email address is the capability, same as in the UI; MCP always needs a token. Marked availability is published for everyone only for a proven address (your own with a token, or confirmed by email); times marked through your signed ask-link are live for you only; anything else waits for that person to confirm by email.

HTTP API quick reference

Times are unix milliseconds; tz is an IANA zone name used for business-hours filtering and email formatting. Full schemas: /openapi.json.

Errors & limits

Errors are JSON { "error": "<code>" }. The ones agents meet most:

Every read of another user’s connected calendar is shown to that user (Settings → Privacy), who can block you; a blocked or unreadable calendar comes back as calendarStatus: "unavailable" and busy for the whole window — never as free.

Booking links & team links

Every user who connects a calendar gets a live booking link at https://whenmeet.me/@<nickname> — no setup: a 30-minute meeting, Mon–Fri 09:00–17:00 in their zone, a Meet link (Google host) or Teams link (Teams-enabled Microsoft 365 work/school host) on every booking, reminder emails 24 h and 1 h before (reminders, any of 15 min–2 days, or off). More link types live at /@<nickname>/<slug>. A team link is one link backed by several people: mode: "all" needs everyone free (a two-person interview panel), mode: "any" books whoever is free, in turn — each teammate inside their own working hours. A team link can claim its own address with teamHandle (https://whenmeet.me/@acme-sales; nicknames and team handles share one namespace). Public endpoints return times and counts only — never anyone’s calendar, hours or member emails. Full schemas in /openapi.json.

Booking webhooks

Set a URL with PUT /api/integrations/webhook (the signing secret is shown once). Every booking.created, booking.cancelled and booking.rescheduled (plus test from POST /api/integrations/webhook/test) is POSTed as JSON with x-whenmeet-event, x-whenmeet-delivery (a unique id per delivery, for de-duplication) and x-whenmeet-signature: t=<unix s>,v1=<hex>, where v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Zapier, Make and n8n can take it from there (a sheet, a CRM without a native row…). HubSpot, Salesforce and Pipedrive are native (Salesforce: external orgs can’t connect until the customer install package ships). Payload schema: BookingEventPayload in the spec.

« verify (Node) »
const [t, v1] = sig.split(',').map((p) => p.split('=')[1]);
const want = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const ok = v1?.length === want.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1));
if (!ok || Date.now() / 1000 - Number(t) > 300) throw new Error('bad signature');

Example: find a slot and book it

« a two-week window from now (the end may be at most 60 days ahead) »
FROM=$(date +%s000); TO=$(( $(date +%s) + 14*86400 ))000

« find slots »
SLOT=$(curl -s https://whenmeet.me/api/availability \
  -H "Authorization: Bearer $WHENMEET_TOKEN" -H "content-type: application/json" \
  -d '{"participants":["alex@example.com","sam@example.org"],
       "from":'$FROM',"to":'$TO',"durationMin":30,"tz":"Europe/Warsaw"}' \
  | jq '.slots[0]')

« book the top slot »
curl -s https://whenmeet.me/api/meetings \
  -H "Authorization: Bearer $WHENMEET_TOKEN" -H "content-type: application/json" \
  -d '{"participants":["alex@example.com","sam@example.org"],
       "startsAt":'$(echo "$SLOT" | jq .start)',"endsAt":'$(echo "$SLOT" | jq .end)',
       "title":"Cross-company sync","conference":"meet","tz":"Europe/Warsaw"}'

Example: book through someone’s link

« times on whenmeet.me/@alex/intro (no auth needed) »
START=$(curl -s https://whenmeet.me/api/public/alex/intro/slots -H "content-type: application/json" \
  -d '{"from":'$FROM',"to":'$TO',"tz":"Europe/Warsaw"}' | jq '.slots[0].start')

« book it (a token skips the bot check) »
curl -s https://whenmeet.me/api/public/alex/intro/book \
  -H "Authorization: Bearer $WHENMEET_TOKEN" -H "content-type: application/json" \
  -d '{"startsAt":'$START',"name":"Sam Example","email":"sam@example.org",
       "guests":["finance@example.org"],"notes":"Pricing questions"}'

Last updated 2026-10-09 · openapi.json · llms.txt · llms-full.txt · MCP for AI agents · WhenMeet.me