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.
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 URLfield 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)
- Usage as App
- Usage as MCP
Installation
- Go to Apps in your workspace
- Search for Google Calendar and install it
- Open the app instance configuration and fill in the required fields
Configuration
| Field | Description |
|---|---|
| Google Calendar API Base URL | Base 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 ID | Google OAuth Application Client ID. Create an OAuth client of type Web application in the Google Cloud Console |
| OAuth2 Client Secret | Google OAuth Client Secret, stored as a workspace secret |
| OAuth Callback URL | Auto-populated on install — paste this value into the Authorized redirect URIs list of your Google OAuth client |
| OAuth Authorize URL | Default https://accounts.google.com/o/oauth2/v2/auth |
| OAuth Token URL | Default https://oauth2.googleapis.com/token |
| OAuth Revoke URL | Default https://oauth2.googleapis.com/revoke |
| OAuth Scopes | Space-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 Endpoint | Auto-populated on install — URL of the MCP endpoint for this instance |
| MCP API Key | Auto-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: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.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.
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.Available Instructions
Every instruction resolves credentials from the workspace configuration. Most operations default tocalendarId: 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
| Instruction | Arguments |
|---|---|
listEvents | calendarId, timeMin, timeMax, singleEvents, orderBy, q, maxResults, pageToken, timeZone, showDeleted, showHiddenInvitations, eventTypes, iCalUID, maxAttendees, privateExtendedProperty, sharedExtendedProperty, syncToken, updatedMin |
getEvent | calendarId, eventId*, maxAttendees, timeZone |
insertEvent | calendarId, 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 |
updateEvent | calendarId, 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 |
patchEvent | calendarId, eventId*, (same fields as updateEvent, only supplied ones change) |
deleteEvent | calendarId, eventId*, sendUpdates |
moveEvent | calendarId, eventId, destination, sendUpdates |
quickAddEvent | calendarId, text*, sendUpdates |
importEvent | calendarId, iCalUID, start, end*, summary, description, location, attendees, recurrence, reminders, status, transparency, visibility, colorId, source, extendedProperties, conferenceDataVersion, supportsAttachments |
listEventInstances | calendarId, eventId*, maxAttendees, maxResults, originalStart, pageToken, showDeleted, timeMax, timeMin, timeZone |
Calendars
| Instruction | Arguments |
|---|---|
getCalendar | calendarId* |
insertCalendar | summary*, description, location, timeZone |
updateCalendar | calendarId*, summary, description, location, timeZone |
patchCalendar | calendarId*, summary, description, location, timeZone |
deleteCalendar | calendarId* |
clearCalendar | calendarId* |
Calendar List
| Instruction | Arguments |
|---|---|
listCalendarList | maxResults, minAccessRole, pageToken, showDeleted, showHidden, syncToken |
getCalendarListEntry | calendarId* |
insertCalendarListEntry | id*, colorRgbFormat, colorId, backgroundColor, foregroundColor, defaultReminders, notificationSettings, selected, summaryOverride, hidden |
updateCalendarListEntry | calendarId*, colorRgbFormat, colorId, backgroundColor, foregroundColor, defaultReminders, notificationSettings, selected, summaryOverride, hidden |
patchCalendarListEntry | calendarId*, (same fields as updateCalendarListEntry) |
deleteCalendarListEntry | calendarId* |
ACL (Sharing)
| Instruction | Arguments |
|---|---|
listAcl | calendarId, maxResults, pageToken, showDeleted, syncToken |
getAclRule | calendarId, ruleId* |
insertAclRule | calendarId, role, scope, sendNotifications |
updateAclRule | calendarId, ruleId*, role, scope, sendNotifications |
patchAclRule | calendarId, ruleId*, role, scope, sendNotifications |
deleteAclRule | calendarId, ruleId* |
Settings
| Instruction | Arguments |
|---|---|
listSettings | maxResults, pageToken, syncToken |
getSetting | setting* |
Colors
| Instruction | Arguments |
|---|---|
getColors | (none) |
Free/Busy
| Instruction | Arguments |
|---|---|
queryFreebusy | timeMin, timeMax, items*, timeZone, groupExpansionMax, calendarExpansionMax |
Arguments flagged with
* are required.DSUL Examples
List the next 25 upcoming events on the user’s primary calendar
Create an event with a Google Meet conference link
Quick-add an event from natural language
Find when a group of people are free over the next 7 days
Share a secondary calendar with a teammate as writer
Error Handling
| HTTP Status | Meaning | Typical Cause |
|---|---|---|
400 | Bad Request | Malformed RFC3339 timestamp, missing required field, conflicting parameters |
401 | Unauthorized | Missing / expired OAuth token, revoked refresh token, user has not connected yet |
403 | Forbidden | Calendar API disabled in the Google Cloud project, scope insufficient for the operation, sharing restricted by Workspace admin |
404 | Not Found | Event/calendar/ACL rule does not exist or the user lost access |
409 | Conflict | Optimistic concurrency failure on update / patch (etag mismatch) |
410 | Gone | syncToken has expired — perform a full sync (omit syncToken) and refresh the token |
429 | Rate Limited | Per-user or per-project quota exhausted. Back off and retry |
500 / 503 | Server Error | Transient 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) — Themcp-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