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 with a 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 with a 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 with 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
Gmail & Calendar
Flexible per-user auth
Who is this for?
This connector is used by three different roles. Jump to the section that matches yours; each one is self-contained.Agent builder
Platform admin
Workspace builder
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 setup accordion below and the Workspace builder tab).
Platform admin (Governance): one-time platform setup
Platform admin (Governance): one-time platform setup
1. Configure the connector
Register the OAuth Application at Google
https://api.studio.prisme.ai/v2/workspaces/slug:google-workspaces/webhooks/oauthCallback on production). Enable the Drive, Docs, Sheets, Gmail and Calendar APIs in the same project, and add the scopes listed in Prerequisites. Save the Client ID + Client Secret.Enter the credentials through the configuration app
google-workspaces workspace and launch its Configuration app at <studio>/apps/google-workspaces (e.g. https://studio.prisme.ai/apps/google-workspaces), also linked as Configuration app on the installed instance. Follow the in-app instructions to paste the Client ID and Client Secret; the app stores them in the core workspace’s secrets for you. Do not edit Studio’s raw Secrets by hand. These credentials stay in the google-workspaces workspace and are never exposed to tenants or end users; token exchange is proxied through the core centralTokenExchange webhook so the client secret never leaves the core workspace.Tell workspaces to use the central client
oauthCentral in the connector configuration app (no client id/secret to enter on their side). Their users then just click Connect.2. Declare the capability in AI Governance
Generic connectors (broad tool surfaces meant to be shared across many agents, like Google Workspaces) are best exposed as a named capability in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.Open AI Governance > Capabilities
Point it at the MCP endpoint
agent_id in the scope is what lets the connector identify and authorize the calling agent.Make it available to agent builders
Smoke-test
oauthCentral, trigger any tool. The user is prompted to connect once (Google sign-in); subsequent calls reuse the stored token transparently and refresh it automatically.- Agent builder (Agent Factory)
- Workspace builder (DSUL)
Agent builder
Goal: let an agent you build in Agent Factory read and act on Google Workspace through MCP tools.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 setup accordion above, §2), so you just pick it from the catalog.Open your agent in Agent Factory
Add the Google Workspaces capability
context_id,agent_id,user_id) are already wired by the admin; there is nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side.Connect a Google account (OAuth modes)
connect_url. Service-account (jwt) and accessToken modes need no per-user sign-in.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
Allowlist your agent
Add the MCP capability to your agent
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.Connect a Google account (OAuth modes)
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:agent_id.oauthCentral) you do not create your own Google client; keep oauthCentral and just enter the read-only scopes; your tenant scope overrides the platform default (the central app’s consent screen must declare these read scopes). Write calls are then rejected by Google with 403. Note this is set at the workspace level: a workspace editor can widen it again; a provider-side restriction is the only hard guarantee.Available Tools
Each tool takes anaction argument selecting the concrete operation, plus the per-action parameters.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
sheets
gmail
getProfile call; it returns {emailAddress, messagesTotal}. Never list messages to discover the connected address.calendar
Error Handling
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.