fix: resolve Cal.com API v2 versioning issues and reduce token overhead

[sahitya-chandra]

Summary

Multiple MCP server tools (get_event_types, get_event_type, get_schedules, etc.) were returning 404 errors because the cal-api-version header sent to the Cal.com API v2 didn't match the version each NestJS controller is pinned to. The API uses custom header-based versioning — a mismatched version means NestJS can't match the route and returns 404.

Root cause: The version override map only had an entry for slots. The event-types and schedules controllers are pinned to older versions (2024-06-14 and 2024-06-11 respectively), but the MCP server was sending the default 2024-08-13 for those paths.

Secondary issue: The override lookup did exact path matching (event-types matched but event-types/123 did not). Changed to match on the first path segment so sub-paths resolve correctly.

Additional improvements:

• Error responses now include the nested errors array from Cal.com API validation responses, so LLMs can understand why a request failed
• create_booking now supports eventTypeSlug + username/teamSlug as an alternative to eventTypeId, matching the Cal.com API v2 contract

Token overhead reduction

Reduced per-tool-call token cost across all tool schemas and responses:

• Removed 40-language enum in addBookingAttendee — replaced with z.string().describe("ISO 639-1 language code (e.g. 'en')") (~100 tokens saved per schema emission). Validation is deferred to the API.
• Shortened .describe() strings across all tool files — removed verbose/redundant phrasing and fixed truncated descriptions (e.g. routing-forms had descriptions cut off mid-sentence). ~200 tokens saved per full tool listing.
• Dropped pretty-printing in ok() — JSON.stringify(data) instead of JSON.stringify(data, null, 2). ~30% smaller responses, which compounds across multi-turn conversations.

Review & Testing Checklist for Human

• Verify version strings are correct: event-types → 2024-06-14, schedules → 2024-06-11, slots → 2024-09-04. These were derived from reading the Cal.com API v2 NestJS controller decorators — please cross-check against the live API or the latest controller source to confirm they haven't changed.
• Test against live API: Run the MCP server locally with a valid API key and verify get_event_types, get_event_type (by ID), get_schedules, and get_availability (with eventTypeId) all return data instead of 404s.
• Test create_booking with slug: Try booking via eventTypeSlug + username instead of eventTypeId to confirm the API accepts it. Note: there is no client-side validation that at least one identification method is provided — validation is deferred to the API.
• Spot-check shortened descriptions: Verify the shortened .describe() strings still convey enough information for LLMs to use the tools correctly. In particular, check that addBookingAttendee's language field (now z.string()) doesn't cause issues when invalid codes are sent — the API should reject them, but confirm the error is surfaced properly.
• First-segment matching safety: The override lookup now uses path.split("/")[0] instead of exact match. Confirm no other endpoint paths start with event-types, schedules, or slots that would be incorrectly matched.

Notes

• The create_booking change makes eventTypeId optional at the schema level. The Cal.com API itself enforces that either eventTypeId or eventTypeSlug + username/teamSlug must be present — no MCP-side validation was added to avoid duplicating that logic.
• The language enum removal means invalid language codes are no longer rejected client-side. The API still validates and the error is now surfaced via formatApiError, so LLMs will see the rejection reason.
• All 184 existing unit tests pass, plus new tests for the added overrides and slug-based booking.

Link to Devin session: https://app.devin.ai/sessions/9e7d8dde273748c789857ef44eddbb9b
Requested by: @sahitya-chandra

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[cubic-dev-ai]

No issues found across 6 files

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
cal-companion-chat	Ignored		Apr 6, 2026 10:23am