The Google Workspaces app provides read/write access to five Google Workspace APIs — Drive, Docs, Sheets, Gmail and Calendar — through their official REST endpoints. It can be consumed two ways: as a remote MCP server that Agent Factory agents call as tools, or as a Builder app whose instructions you call directly from DSUL. The MCP surface groups every operation into five entity tools (drive, docs, sheets, gmail, calendar), each driven by an action argument, and runs in the tenant app-instance context (it resolves the installing workspace’s own credentials). Authentication is per-user and supports several modes:
- Per-user OAuth2 — central client (
oauthCentral, recommended) — one Google OAuth Application is registered once by the platform maintainer; every end user signs in with their own Google account. Nothing to register per tenant: each workspace just installs the app and clicks Connect. - Per-user OAuth2 — tenant client (
oauth) — paste your own Google OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (PKCE authorization-code flow). - Service account — JWT Bearer (
jwt) — a Google service-account key, with optional domain-wide delegation (subject) to impersonate users across a Workspace domain. No interactive sign-in. - Direct access token (
accessToken) — a caller-managed Google access token, used as-is with no exchange.
Drive, Docs & Sheets
Browse and manage Drive files, folders and sharing permissions, create and edit Docs, read and write Sheets values and structure
Gmail & Calendar
Read, send, label and organize Gmail messages, drafts and threads; list, create and update Calendar events and query free/busy
Flexible per-user auth
Per-user OAuth (central or tenant client), service-account JWT with optional domain-wide delegation, or a direct access token
Who is this for?
This connector is used by three different roles. Jump to the tab that matches yours — each one is self-contained.Agent builder
You build agents in Agent Factory and want them to read and act on Google Workspace. → Agent builder tab.
Platform admin
You run the platform and set up the shared Google OAuth client once for everyone. → Platform admin tab.
Workspace builder
You write Builder automations (DSUL) that call Google operations directly. → Workspace builder tab.
Prerequisites (Google side)
- A Google account (or a Google Workspace domain for service-account / domain-wide delegation).
- The Google APIs you intend to call must be enabled in the Cloud project: Drive, Docs, Sheets, Gmail, Calendar.
- An OAuth client or service-account key, depending on the auth mode (see the Platform admin and Workspace builder tabs).
- Agent builder (Agent Factory)
- Platform admin (Governance)
- Workspace builder (DSUL)
Goal: let an agent you build in Agent Factory read and act on Google Workspace through MCP tools.This connector runs in the tenant app-instance context: your agent is authorized two ways at once — it is identified by the
Before an agent can call the connector, a Workspace builder must have installed and configured the Google Workspaces app in a workspace (see the Workspace builder tab), and — for the central OAuth mode — a Platform admin must have provisioned the shared OAuth client (see the Platform admin tab).
agent_id that Agent Factory injects through the capability Scope, and that agent must appear in the connector’s authorized-agents allowlist (managed in the configuration app). The Google access token itself is resolved server-side from the configured auth mode.There are two ways to wire it up. Pick based on how much isolation you need.Option A — Enable the shared capability from the catalog
The fastest path: a Platform admin has already published a Google Workspaces capability (see the Platform admin tab, §2), so you just pick it from the catalog.Open your agent in Agent Factory
Open the agent you want to extend and go to its capabilities / tools.
Add the Google Workspaces capability
Browse the capability catalog, select Google Workspaces, and enable it. The MCP endpoint URL and the Scope (
context_id,agent_id,user_id) are already wired by the admin — nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side.Convenient, but your agent runs against a shared, platform-managed instance: its Google credentials are owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments.
Option B — Run it from your own workspace (recommended)
For production agents, install the connector in your own workspace and point the agent at that workspace’s MCP endpoint.Install and configure the connector in your workspace
Follow the Workspace builder tab: install Google Workspaces in your workspace, open its Configuration app, choose the auth mode and connect a Google account.
Allowlist your agent
In that workspace’s config app, open Authorized agents and tick your agent (the Install capability button does this for you).
Add the MCP capability to your agent
In your agent, add a capability pointing at your workspace’s MCP Endpoint URL, and set its Scope to:The
agent_id is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit “agent could not be identified” message. This Scope is separate from the Google OAuth scopes.Brief the agent in its system prompt
Whichever option you pick, wiring the capability is not enough — the agent must know the MCP exists and when to use it. Copy-pasteable starter:Legacy AI Knowledge agents (no native MCP picker): add the connector under Advanced > Tools > MCP and paste the MCP Endpoint URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its
agent_id.Available Tools
Each tool takes anaction argument selecting the concrete operation, plus the per-action parameters.| Tool | Description |
|---|---|
drive | Google Drive — files & permissions. Actions: list, get, create, update, delete, copy, export, permissionsList, permissionsCreate, permissionsDelete. |
docs | Google Docs. Actions: get, create, batchUpdate. |
sheets | Google Sheets. Actions: get, create, valuesGet, valuesUpdate, valuesAppend, valuesClear, batchUpdate. |
gmail | Gmail (current user). Actions: getProfile, messagesList, messagesGet, messagesSend, messagesModify, messagesTrash, draftsCreate, labelsList, threadsGet. |
calendar | Google Calendar. Actions: eventsList, eventsGet, eventsInsert, eventsUpdate, eventsDelete, calendarList, freebusy. |
Output Formats
Every tool accepts anoutputFormat argument that controls the MCP response shape:verbose(default) — human-readable text optimized for LLM consumptioncompact— concise machine-readable JSON instructuredContent
Tool Details
drive
| Parameter | Required | Description |
|---|---|---|
action | Yes | One of list, get, create, update, delete, copy, export, permissionsList, permissionsCreate, permissionsDelete. |
fileId | For get/update/delete/copy/export/permissions* | Drive file id. |
q | No | Search query (list), e.g. mimeType='application/vnd.google-apps.folder'. |
mimeType | For export | Target MIME type, e.g. application/pdf. |
body | For create/update/copy/permissionsCreate | File metadata, or {role,type,emailAddress} for a permission. |
sheets
| Parameter | Required | Description |
|---|---|---|
action | Yes | One of get, create, valuesGet, valuesUpdate, valuesAppend, valuesClear, batchUpdate. |
spreadsheetId | For all but create | Target spreadsheet id. |
range | For values* | A1 notation, e.g. Sheet1!A1:C10. |
valueInputOption | For valuesUpdate/valuesAppend | RAW or USER_ENTERED. |
body | For create/values*/batchUpdate | Spreadsheet resource, {values:[[...]]}, or {requests:[...]}. |
gmail
| Parameter | Required | Description |
|---|---|---|
action | Yes | One of getProfile, messagesList, messagesGet, messagesSend, messagesModify, messagesTrash, draftsCreate, labelsList, threadsGet. |
id | For messagesGet/Modify/Trash, threadsGet | Message or thread id. |
q | No | Gmail search query (messagesList), e.g. from:x is:unread. |
body | For messagesSend/draftsCreate/Modify | Send/draft: {to,subject,text|html,cc,bcc,replyTo,inReplyTo,threadId} as plain strings (server-side MIME + base64 — never encode yourself); modify: {addLabelIds,removeLabelIds}. |
Resolve “me” / “my email” with a single
getProfile call — it returns {emailAddress, messagesTotal}. Never list messages to discover the connected address.calendar
| Parameter | Required | Description |
|---|---|---|
action | Yes | One of eventsList, eventsGet, eventsInsert, eventsUpdate, eventsDelete, calendarList, freebusy. |
calendarId | No | Calendar id (defaults to primary). |
eventId | For eventsGet/Update/Delete | Target event id. |
body | For eventsInsert/Update, freebusy | Event resource {summary,start,end,attendees}, or freebusy request {timeMin,timeMax,items}. |
Error Handling
| HTTP code | Meaning |
|---|---|
400 | Bad request — invalid parameters or malformed body (e.g. bad A1 range, invalid file metadata). |
401 | Unauthorized — the Google access token is missing, expired or revoked. The user must reconnect (OAuth modes). |
403 | Forbidden — insufficient OAuth scope, the target API is not enabled in the Cloud project, or the account lacks access to the resource. |
404 | Not found — the file, document, spreadsheet, message or event id does not exist or is not visible to the account. |
429 | Rate limit / quota exceeded — back off and retry. |
500 / 503 | Google service error — transient; retry shortly, no reconnection needed. |
Common Issues
“This agent is not authorized to use this connector” — The calling agent is not in the allowlist. Open the configuration app → Authorized agents → tick this agent (or enable Allow all agents) and Save. “The calling agent could not be identified” — The MCP capability Scope does not declareagent_id, so Agent Factory never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability, then allow the agent in the config app.
“Google is not connected for this user” — No per-user OAuth token. Open the configuration app (OAuth mode) and click Connect, or use the agent’s connect flow.
“Google token refresh failed … must reconnect” — The stored refresh token was revoked or expired (Google invalidated it). The connection is dropped automatically; the user must reconnect from the config app.
“Google OAuth is not configured” — Neither a tenant OAuth client nor the central platform client is available. Set the OAuth client ID/secret in the config app, or ask the platform maintainer to provision the central OAuth client.
Gmail send fails or arrives garbled — Pass to, subject, text/html as plain strings in body. The server builds and base64-encodes the MIME message itself — never base64-encode the content yourself.
External Resources
Google Workspace APIs
Official reference for the Drive, Docs, Sheets, Gmail and Calendar REST APIs.
Tool Agents
Learn how Agent Factory agents consume MCP tools in Prisme.ai.