How to connect Cal.com to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Cal.com from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Cal.com tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Cal.com call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

Reads succeeding and writes 403ing is the signature of a scope or role boundary, not a broken connection. The engines' taught causes are the map: missing OAuth scopes (booking writes need the BOOKING_WRITE-class scope, which the connection carries or not), organization-only endpoints that a personal account cannot reach no matter what, and user booking limits on the specific event type. Our two hosted causes still apply on top: workspace or project access (an event type in an org the connected account does not manage) and the placeholder trap (a booking uid the agent invented instead of one from cal_fetch_all_bookings). Have the agent quote the error, name the endpoint, and confirm which account authorized the connection before reconnecting, because a reconnect will not fix an org boundary.

Ask the agent to diagnose it:

Call cal_fetch_all_bookings and show me which bookings exist. Then quote the exact 403 from the failing write and which endpoint it hit. Do not retry the write yet.

Cal.com documents a 120-requests-per-minute default limit for API-key and unauthenticated calls, which is the figure the AI Overviews quote, and responses carry rate-limit headers the agent can read. An agent walking a schedule, then event types, then a slot search, one call at a time, is unlikely to trip it, but a loop re-checking availability every few seconds will. The fix is to stop polling: ask for the slots you need once, work from cal_get_available_slots_info results, and have the agent report the rate-limit header it saw rather than retrying blindly.

Ask the agent to diagnose it:

Tell me how many Cal.com calls you made in the last minute and whether any were polling in a loop. Quote the exact rate-limit response. Do not call Cal.com again until I reply.

The engines' answer to this symptom is self-hosted MCP mechanics: a missing API key, an incorrect JSON config, or an outdated package, fixed with npx -y @calcom/cal-mcp@latest and a CAL_API_KEY. None of that exists in this flow. The hosted causes are the two real ones: the connection or pairing is incomplete (confirm the plugin installed with --enable, both pairing commands ran, and Cal.com shows as connected), or schemas load on demand, so the first Cal.com call in a fresh session can arrive before the catalog and needs one retry. If most tools work and one name fails, that name is wrong rather than missing.

Ask the agent to diagnose it:

List the Cal.com tools you actually have access to. If there are none, say so plainly. If there are, tell me which one fetches bookings and use that exact name.

Slot availability and booking creation are different gates. Seeing free slots means the read surface works; failing to create a booking means one of the write gates is closed: the event type requires a field the agent did not supply (location, time zone, or a custom question the type enforces), the attendee email fails validation, or the event type's booking limits are exhausted. The engines' p3 answers add the org/team role dimension: a connection that can read org data can still be blocked from writing. Have the agent show you the exact error from cal_confirm_booking_by_uid or the create call, then check the event type's requirements rather than reconnecting.

Ask the agent to diagnose it:

Show me the exact error from the failed booking create, then fetch the event type's details and tell me which required fields it declares. Do not retry the create yet.

Try reconnecting Cal.com and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Cal.com: link your Cal.com account once in the browser and Hermes Agent can call the Cal.com API through 168 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Cal.com in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Cal.com in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Cal.com working from chat.

Cal.com ships a hosted MCP server at mcp.cal.com, OAuth 2.1, no API key, and it is the best-of answer everywhere; there is no beating it at its own game. The difference is the client it serves. That MCP endpoint connects to generic MCP clients through their config files. ClawLink is the Hermes-specific route: you pair Hermes once with hermes clawlink begin and hermes clawlink finish, connect Cal.com in the dashboard, and the 168 tools appear in chat with no MCP endpoint configured anywhere. If you live in an MCP client and like its config, Cal.com's own server is the right tool. If you run Hermes Agent and want the connection to be a one-time browser approval, this page is it.

The full booking surface: fetch bookings and references, confirm and cancel bookings by uid, get available slots, add attendees, and manage event types, schedules, and teams. The answer ChatGPT gives as "what you generally cannot do", an autonomous agent that reads and modifies bookings, is exactly the set of 168 tools. The writes to be deliberate about are the user-visible ones: confirming a booking sends confirmation, cancelling one notifies the invitee, and adding an attendee changes a live meeting. Slot checking and schedule reads are the safe, high-value surface.

Your Cal.com account's access, through OAuth. The scopes the engines teach for Cal.com API v2 are the useful map: PROFILE_READ and PROFILE_WRITE for profile data and BOOKING_WRITE for creating and managing bookings. Some endpoints are organization-only, so a personal-account connection cannot reach org-level routes no matter how the prompt is phrased, and booking limits on an event type cap what the agent can create. If a call fails with a permissions error, the first questions are which Cal.com account authorized the connection and whether the endpoint is org-scoped.

The engines' answer is yes, with least privilege, and the specifics are worth following: scoped OAuth instead of long-lived keys, human confirmation before booking changes, and care about what the agent does with attendee data. This setup gives you the scoped OAuth (the token is held server-side, never written to a local config, and revocable from the dashboard) and the rest is prompt discipline: have the agent check slots and fetch bookings before it writes, and make it confirm the exact booking before cancel or confirm. A booking is a promise to another human's calendar, which is why the read-first pattern is the safe one.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.