Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt

Use this file to discover all available pages before exploring further.

Google Calendar The Google Calendar app provides read/write access to a user’s Google Calendar through the Calendar API v3. It can be used either as a Builder app (automations call Calendar instructions directly) or as a remote MCP server consumed by an AI agent. Each tenant configures its own Google OAuth Application; end-users sign in with their own Google account and tokens are stored per (user × tenant). The connector exposes 32 underlying operations, grouped into 7 entity tools covering events, calendars, the user’s calendar list, sharing rules (ACL), user settings, the color palette and free/busy queries.

Events

Create, search, update, move, import and expand recurring events; quick-add from natural language; attach Google Meet conferences

Calendars & Sharing

Manage secondary calendars, the user’s calendar list, and ACL rules to share calendars with users, groups or domains

Availability & Settings

Query free/busy across multiple calendars and read user settings, time zones and the color palette

Prerequisites

  • A Google account with access to the calendar you want to expose. For Google Workspace, the workspace admin may need to allow third-party OAuth apps.
  • A Google Cloud project with the Google Calendar API enabled at console.cloud.google.com/apis/library/calendar-json.googleapis.com.
  • A Google OAuth 2.0 Client of type Web application, created at console.cloud.google.com/apis/credentials. The Authorized redirect URIs must contain the value shown in the OAuth Callback URL field of the installed app instance (auto-populated on install — copy it back into the Google Cloud Console after installation).
  • An OAuth consent screen configured in the Google Cloud project. While the app is in Testing state, add the end-user’s email to Test users. The full Calendar scope (https://www.googleapis.com/auth/calendar) is classed sensitive by Google and goes through Google’s verification process when the consent screen moves to Production.
  • Base URL (default: https://www.googleapis.com/calendar/v3)

Installation

  1. Go to Apps in your workspace
  2. Search for Google Calendar and install it
  3. Open the app instance configuration and fill in the required fields

Configuration

FieldDescription
Google Calendar API Base URLBase URL of the Calendar API (default https://www.googleapis.com/calendar/v3)
API Token (fallback)Optional static OAuth access token used as a shared fallback for all users of this tenant. Stored as a workspace secret. Most deployments leave this empty and rely on per-user OAuth instead.
OAuth2 Client IDGoogle OAuth Application Client ID. Create an OAuth client of type Web application in the Google Cloud Console
OAuth2 Client SecretGoogle OAuth Client Secret, stored as a workspace secret
OAuth Callback URLAuto-populated on install — paste this value into the Authorized redirect URIs list of your Google OAuth client
OAuth Authorize URLDefault https://accounts.google.com/o/oauth2/v2/auth
OAuth Token URLDefault https://oauth2.googleapis.com/token
OAuth Revoke URLDefault https://oauth2.googleapis.com/revoke
OAuth ScopesSpace-separated Google API scopes. Default https://www.googleapis.com/auth/calendar (full read/write). Other common values: calendar.events, calendar.readonly, calendar.settings.readonly
Refresh Token TTL (seconds)Default 15552000 (180 days, Google’s max)
Max Tool Payload (KB)Threshold above which MCP responses are auto-compacted into a summary + recovery hints to avoid overflowing the LLM context. Default 50. Raise it (for example 200) when targeting LLMs with 1M-token windows
MCP EndpointAuto-populated on install — URL of the MCP endpoint for this instance
MCP API KeyAuto-populated on install — signed key used in the mcp-api-key header. Do not modify
MCP Endpoint, MCP API Key and OAuth Callback URL are generated automatically by the onInstall flow. The OAuth credentials below (OAuth2 Client ID, OAuth2 Client Secret) must be filled in manually after creating the OAuth client in the Google Cloud Console.

Authorize end-users

Once the app instance is configured, each end-user authorizes their own Google account through a browser-based consent screen:
1

Trigger the connect flow

From an MCP client (Agent Creator capability or any tool client), call any data tool. If no OAuth session exists for the current user × tenant, the MCP server returns a connector_auth_required payload with a connect_url. Alternatively, call the connect tool explicitly to receive the same payload.
2

Open the connect URL

Open the returned URL in a browser tab where the user is already authenticated to Prisme.ai. The platform redirects to the Google OAuth consent screen.
3

Grant access

The user reviews the requested scopes (default https://www.googleapis.com/auth/calendar) and clicks Allow. Google redirects back to the platform’s oauthCallback webhook.
4

Confirmation

The user sees a Connection complete page and can close the tab. The platform has stored an access token plus refresh token as user-scoped secrets — both are tenant-prefixed so they do not leak across app instances.
Each user’s OAuth tokens are scoped per (user × tenant). A user who has authorized in tenant A does not gain access in tenant B — they must run the connect flow again per app instance. Refresh tokens are rotated by Google on each refresh and live up to 180 days when idle.

Available Instructions

Every instruction resolves credentials from the workspace configuration. Most operations default to calendarId: primary — pass an explicit calendar ID or email to operate on another calendar the user has access to. List operations accept maxResults and pageToken for pagination, plus syncToken for incremental sync.

Events

InstructionArguments
listEventscalendarId, timeMin, timeMax, singleEvents, orderBy, q, maxResults, pageToken, timeZone, showDeleted, showHiddenInvitations, eventTypes, iCalUID, maxAttendees, privateExtendedProperty, sharedExtendedProperty, syncToken, updatedMin
getEventcalendarId, eventId*, maxAttendees, timeZone
insertEventcalendarId, start, end, summary, description, location, attendees, recurrence, reminders, colorId, conferenceData, conferenceDataVersion, attachments, supportsAttachments, transparency, visibility, status, extendedProperties, sendUpdates, maxAttendees, id, guestsCanInviteOthers, guestsCanModify, guestsCanSeeOtherGuests, anyoneCanAddSelf, source, originalStartTime, recurringEventId
updateEventcalendarId, eventId*, start, end, summary, description, location, attendees, recurrence, reminders, colorId, conferenceData, conferenceDataVersion, attachments, supportsAttachments, transparency, visibility, status, extendedProperties, sendUpdates, maxAttendees, guestsCanInviteOthers, guestsCanModify, guestsCanSeeOtherGuests, anyoneCanAddSelf, source, originalStartTime, recurringEventId
patchEventcalendarId, eventId*, (same fields as updateEvent, only supplied ones change)
deleteEventcalendarId, eventId*, sendUpdates
moveEventcalendarId, eventId, destination, sendUpdates
quickAddEventcalendarId, text*, sendUpdates
importEventcalendarId, iCalUID, start, end*, summary, description, location, attendees, recurrence, reminders, status, transparency, visibility, colorId, source, extendedProperties, conferenceDataVersion, supportsAttachments
listEventInstancescalendarId, eventId*, maxAttendees, maxResults, originalStart, pageToken, showDeleted, timeMax, timeMin, timeZone

Calendars

InstructionArguments
getCalendarcalendarId*
insertCalendarsummary*, description, location, timeZone
updateCalendarcalendarId*, summary, description, location, timeZone
patchCalendarcalendarId*, summary, description, location, timeZone
deleteCalendarcalendarId*
clearCalendarcalendarId*

Calendar List

InstructionArguments
listCalendarListmaxResults, minAccessRole, pageToken, showDeleted, showHidden, syncToken
getCalendarListEntrycalendarId*
insertCalendarListEntryid*, colorRgbFormat, colorId, backgroundColor, foregroundColor, defaultReminders, notificationSettings, selected, summaryOverride, hidden
updateCalendarListEntrycalendarId*, colorRgbFormat, colorId, backgroundColor, foregroundColor, defaultReminders, notificationSettings, selected, summaryOverride, hidden
patchCalendarListEntrycalendarId*, (same fields as updateCalendarListEntry)
deleteCalendarListEntrycalendarId*

ACL (Sharing)

InstructionArguments
listAclcalendarId, maxResults, pageToken, showDeleted, syncToken
getAclRulecalendarId, ruleId*
insertAclRulecalendarId, role, scope, sendNotifications
updateAclRulecalendarId, ruleId*, role, scope, sendNotifications
patchAclRulecalendarId, ruleId*, role, scope, sendNotifications
deleteAclRulecalendarId, ruleId*

Settings

InstructionArguments
listSettingsmaxResults, pageToken, syncToken
getSettingsetting*

Colors

InstructionArguments
getColors(none)

Free/Busy

InstructionArguments
queryFreebusytimeMin, timeMax, items*, timeZone, groupExpansionMax, calendarExpansionMax
Arguments flagged with * are required.

DSUL Examples

List the next 25 upcoming events on the user’s primary calendar

- Google Calendar.events:
    action: list
    calendarId: primary
    timeMin: '{% date({{run.date}}).iso %}'
    singleEvents: true
    orderBy: startTime
    maxResults: 25
    output: upcoming
- emit:
    event: calendar.upcoming.fetched
    payload:
      count: '{{upcoming.length}}'
- Google Calendar.events:
    action: insert
    calendarId: primary
    summary: 'Project sync — {{project.name}}'
    description: 'Weekly status meeting'
    start:
      dateTime: '2026-06-01T14:00:00+02:00'
    end:
      dateTime: '2026-06-01T15:00:00+02:00'
    attendees:
      - email: '{{lead.email}}'
      - email: '{{client.email}}'
    conferenceDataVersion: 1
    conferenceData:
      createRequest:
        requestId: '{{run.id}}'
        conferenceSolutionKey:
          type: hangoutsMeet
    sendUpdates: all
    output: createdEvent

Quick-add an event from natural language

- Google Calendar.events:
    action: quickAdd
    calendarId: primary
    text: 'Lunch with Bob tomorrow 12pm-1pm at the Italian place'
    sendUpdates: none
    output: quickEvent

Find when a group of people are free over the next 7 days

- set:
    name: weekFromNow
    value: '{% date({% {{run.date}} + 604800000 %}).iso %}'
- Google Calendar.freebusy:
    action: query
    timeMin: '{% date({{run.date}}).iso %}'
    timeMax: '{{weekFromNow}}'
    timeZone: 'Europe/Paris'
    items:
      - id: 'alice@example.com'
      - id: 'bob@example.com'
      - id: 'team-room@example.com'
    output: availability

Share a secondary calendar with a teammate as writer

- Google Calendar.acl:
    action: insert
    calendarId: '{{teamCalendarId}}'
    role: writer
    scope:
      type: user
      value: 'alice@example.com'
    sendNotifications: true
    output: aclRule

Error Handling

HTTP StatusMeaningTypical Cause
400Bad RequestMalformed RFC3339 timestamp, missing required field, conflicting parameters
401UnauthorizedMissing / expired OAuth token, revoked refresh token, user has not connected yet
403ForbiddenCalendar API disabled in the Google Cloud project, scope insufficient for the operation, sharing restricted by Workspace admin
404Not FoundEvent/calendar/ACL rule does not exist or the user lost access
409ConflictOptimistic concurrency failure on update / patch (etag mismatch)
410GonesyncToken has expired — perform a full sync (omit syncToken) and refresh the token
429Rate LimitedPer-user or per-project quota exhausted. Back off and retry
500 / 503Server ErrorTransient Google Calendar API error. Retry with exponential backoff

Common Issues

“Not configured” — The app instance has no OAuth Client ID/Secret. Create an OAuth client in the Google Cloud Console and paste the credentials into the app configuration. “Invalid API key” (MCP) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key. “Credentials lookup failed” — The MCP endpoint could not reach the getConfig webhook of the installed app. Verify that the app instance is still installed in the expected workspace. connector_auth_required — The calling user has no Google OAuth session yet for this tenant. The response payload includes a connect_url; relay it to the user so they can authorize their Google account. redirect_uri_mismatch during the OAuth dance — The value of OAuth Callback URL in the app config has not been added to the Authorized redirect URIs of the Google OAuth client. Copy it back into the Google Cloud Console and retry. Token has been expired or revoked (401 after a previously working setup) — The refresh token has been invalidated (user revoked access, password change, more than 180 days idle, or Google moved the OAuth app from Testing to Production). Ask the user to run the connect flow again.

External Resources

Google Calendar API v3

Official Google Calendar REST API reference

Tool Agents

Build AI agents that call MCP tools dynamically