novacal-mcp-server

A remote MCP server for Novacal. It gives your AI client eight tools to read your event types, check availability, and book, reschedule, or cancel meetings.

It runs as a single Cloudflare Worker and speaks Streamable HTTP. You connect once with OAuth, paste your Novacal API key, and your client keeps working from there.

---

Connect

The hosted server is at https://mcp.novacal.io/mcp.

Claude Code

claude mcp add --transport http novacal https://mcp.novacal.io/mcp

Cursor, Windsurf, or any client with an MCP config file

{
  "mcpServers": {
    "novacal": {
      "type": "http",
      "url": "https://mcp.novacal.io/mcp"
    }
  }
}

Claude Desktop and claude.ai

Add a custom connector and paste the same URL.

On first connect your client opens the sign-in page. Paste your Novacal API key and press Connect. That is the whole setup.

---

Tools

Tool	What it does	Arguments
novacal_get_event_types	List event types on the account	scope (personal or team, optional)
novacal_get_event_type	Fetch one event type	id
novacal_create_event_type	Create an event type	name, slug, type, duration, hidden_from_profile, color + 10 optional fields
novacal_get_availability	Free slots for an event type in a date range	event_type_id, start, end, timezone (optional)
novacal_get_events	List events on the account	none
novacal_create_event	Book an event	event_type_id, start, end, timezone, time_format, location and form_field_answers (optional)
novacal_cancel_event	Cancel a future event	id, cancellation_reason (optional)
novacal_reschedule_event	Move a future event	id, start, end, timezone, time_format, user_role and form_field_answers (optional)

Read tools are marked read-only and idempotent. novacal_cancel_event is marked destructive, so clients that ask before destructive calls will ask.

Event type scope

novacal_get_event_types takes an optional scope:

{ "scope": "personal" }

Use personal for your own event types and team for team event types. Leave it out to get both. The server tells the model to prefer personal unless you ask for a team event type.

Availability date ranges

start and end are plain YYYY-MM-DD dates. The range is start-inclusive and end-exclusive:

[start 00:00, end 00:00)

For a single day, pass the next day as end:

{
  "event_type_id": 123,
  "start": "2026-05-29",
  "end": "2026-05-30",
  "timezone": "Europe/Amsterdam"
}

That returns availability for May 29, 2026. Passing the same date for start and end is an empty range and returns nothing.

Timezones

timezone takes an IANA name such as Europe/Amsterdam, America/New_York, or Asia/Tokyo. It defaults to UTC when omitted.

On connect the server reads your Novacal profile timezone and puts it in the server instructions. So the model reads relative dates in your timezone and shows times in your timezone, unless you ask for another one.

---

How auth works

1. Your client starts an OAuth flow against the Worker.
2. The Worker serves /authorize and asks for your Novacal API key.
3. It verifies the key with GET /v1/users/me.
4. It encrypts the key into the OAuth session props and completes the flow.

The key is only recoverable with your access token. It is never written to storage in readable form, never echoed back into the page, and is kept out of the grant metadata, which is stored unencrypted.

Removing the connection in your client does not revoke the key. To cut off access, rotate the key in Novacal.

---

Local development

You need Node 20+ and a Cloudflare account for deploys.

npm install
npm run dev

Endpoint	URL
MCP	http://127.0.0.1:8787/mcp
Sign-in page	http://127.0.0.1:8787/authorize
Health check	http://127.0.0.1:8787/health

npm run dev uses the dev Wrangler environment. It simulates KV and D1 locally and points at a Novacal API on http://localhost:8010, so it never touches production resources.

To poke at the tools by hand:

npx @modelcontextprotocol/inspector

Checks

npm run check    # tsc --noEmit
npm run lint     # biome check
npm run format   # biome check --write
npm test         # vitest run

CI runs check, lint, and test on Node 20 for every push and pull request.

---

Deploy

Create the Cloudflare resources once:

npx wrangler kv namespace create OAUTH_KV
npx wrangler d1 create novacal-mcp-server-db

Copy the returned IDs into wrangler.toml under OAUTH_KV and DB, then apply the schema:

npx wrangler d1 execute novacal-mcp-server-db --remote --file=./migrations/0001_user_credentials.sql

Deploy the production environment:

npm run deploy

Note: the user_credentials table is legacy. Credentials now live in the encrypted OAuth session and nothing reads or writes this table. It and the DB binding stay only so existing deployments keep validating.

Configuration

Name	Type	Value
NOVACAL_API_BASE_URL	var	https://api.novacal.io in production, http://localhost:8010 in dev
OAUTH_KV	KV namespace	OAuth client, grant, and token storage
DB	D1 database	legacy, unused

---

How it is put together

src/
├── index.ts            OAuthProvider wiring, /authorize, metadata routes
├── auth.ts             API key verification and the sign-in page
├── mcp.ts              tool registration and server instructions
├── api.ts              Novacal HTTP client, UpstreamApiError, 30s timeout
├── responses.ts        okResult / failedResult envelopes
├── types.ts            Env, session props, Novacal types
└── handlers/
    ├── event-types.ts  list, get, create
    ├── events.ts       list, create, cancel, reschedule
    └── availability.ts availability lookup

Handlers are plain async functions with no MCP imports, so they are easy to test on their own. Every tool wraps its handler in a try/catch and returns an isError result instead of throwing. Failures reach the model as a short hint, not a raw JSON dump:

401 — Novacal API key is invalid or revoked. Re-authorize at /authorize.
429 — Rate limited by the Novacal API. Wait a moment before retrying.

Calls to the Novacal API time out after 30 seconds.

Public routes

Route	Purpose
GET /	server name and status
GET /health	health check
GET /.well-known/oauth-protected-resource	RFC 9728 metadata, with /mcp suffix variant
GET POST /authorize	sign-in page and form post
POST /token, POST /register	handled by OAuthProvider
POST /mcp	the MCP endpoint, requires a bearer token

---

Links

• Novacal
• Model Context Protocol
• MCP registry entry — io.github.ste7/novacal-mcp-server