Guides

Connections

The agent can read a calendar and, once you approve it, update an existing event - Google Calendar in full, Apple Calendar with one exception.

What it can and can't do

• Lists connected calendars and their events.
• Changes the title, start or end of an existing event.

Can't

• Never creates or deletes an event.
• Doesn't search for free slots between attendees.
• Never books anything by phone on your behalf.

Connecting a Google account

Connect a Google account in the portal under Connections (the Integrations item in the portal menu). Once the account is connected, the same API key sees the same thing over both REST and MCP - no separate sign-in needed.

Disconnecting is only possible in the portal - neither REST nor MCP has an endpoint for it.

Apple Calendar

Connects with an app-specific password (not your regular Apple Account password), also in the portal under Connections.

list_calendar_events and REST GET /v1/integrations/{id}/events support Apple Calendar. Use the returned opaque externalId unchanged as eventId for get_calendar_event and updates; it is not an iCalendar UID.

calendarId must be one of the addresses returned by list_calendars - anything else is rejected with 400 calendar_invalid_calendar.

Sequence for an agent

Updating an event is always six steps, in this order:

• 1. list_integrations - connected calendars and their integrationId.
• 2. list_calendars - the calendars of that connection and their calendarId.
• 3. list_calendar_events, then get_calendar_event with the returned externalId as eventId - reads the event and its current sourceRevision.
• 4. propose_calendar_update - prepares the change, writes nothing yet.
• 5. User approval - the agent shows the original values and the proposal, and only then continues.
• 6. confirm_calendar_update with confirm: true - only this step writes the change to Google/Apple.

REST equivalents: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, and finally PATCH /v1/integrations/{id}/events/{eventId} with the body {calendarId, sourceRevision, patch, confirm: true}.

Errors

• calendar_stale_revision - The event changed elsewhere in the meantime - read it again (get_calendar_event) and get the new proposal approved.
• calendar_oauth_failed - Google rejected the sign-in - the connection needs to be redone in the portal.
• calendar_unauthorized - The connection stopped being valid (access revoked, token expired) - reconnect the account.
• calendar_confirmation_required - A write without confirm: true - only confirm the proposal after the user has approved it.
• calendar_verification_failed - The write went through, but a fresh readback doesn't match what was sent - check the state manually, don't blindly retry.

The full table of every code is in the Google Calendar section of the REST API reference and in the MCP error reference.

Security

Access tokens for a Google or Apple account are never returned over REST or MCP and are stored encrypted. Disconnecting a calendar is only possible in the portal.