Secure Google Workspace access for AI agents

Through Google Workspace, agents can search and draft mail, read and create Drive files, manage calendar events, read and send Chat messages, and look up people in your directory – every call runs through your policies and is logged for audit. A single catalog resource covers all five surfaces, and each user acts only as themselves: the tools inherit that user's own Workspace permissions.

Credential modes

Google Workspace supports bring your own app only. Google does not support dynamic client registration, and its Workspace scopes are classed as sensitive and restricted, so your organization registers its own OAuth client in a Google Cloud project you control and supplies the client ID and secret. Owning the client keeps consent, scope review, and revocation inside your own tenant. See Credential modes for how the modes compare.

Before you begin

• A Google Cloud project you control, parented to your Cloud organization. Billing is not required, but org parentage is if you want the Internal consent audience.
• An accepted Developer Preview enrollment for that project. Google gates the Workspace MCP endpoints behind its Developer Preview Program, so apply early: acceptance can take time.
• A Google Workspace account for every user who will use these tools. Consumer Gmail accounts can connect, but the Chat and directory tools only return data for Workspace accounts.
• A Google Workspace super admin, able to configure the OAuth consent screen and trust the OAuth client in the Admin console.
• Administrator access to your Agent Authority workspace, to add the resource.

Setup moves between two consoles and takes longer than most. You copy a redirect URI in the Agent Authority console, do the bulk of the work in Google Cloud and the Google Admin console, then return to the console and paste the credentials. Keep both tabs open as you work.

Setup

1. Copy the redirect URI

In the Agent Authority console, go to Resources → Add Resource and select Google Workspace. Google Workspace is bring-your-own-app only, so the credentials form opens as soon as you select it, with no mode to pick.

Copy the Redirect URI shown on the form. It includes your tenant's region, so copy it rather than typing it. It takes the form https://oauth.aisecurity.services.<region>.connect.secureauth.com/auth/callback.

Leave this page open. You come back to it in step 4.

2. Register an OAuth client in Google Cloud

Sign in to console.cloud.google.com and work through the four parts below. They all target one Cloud project, created under your Cloud organization.

Enroll in the Developer Preview

Google delivers the Workspace MCP servers through its Developer Preview Program, and the endpoints are gated on it.

Open developers.google.com/workspace/preview, sign in with an account on your Workspace domain, and enroll the project that will own the OAuth client. Wait for the status to read accepted. Enrollment is tied to a specific project, so if you do not have one yet, create it first in the next part and come back.

Create the project and enable the APIs

Create the project under your Cloud organization, then point the gcloud CLI at it. Org parentage is what makes the Internal consent audience available later:

gcloud organizations list
gcloud projects create PROJECT_ID --name="PROJECT_NAME" --organization=ORG_ID
gcloud config set project PROJECT_ID
gcloud projects describe PROJECT_ID

gcloud organizations list gives you the ORG_ID to pass to projects create. The describe call at the end confirms the project is ACTIVE and that its parent is the organization, not your personal account.

Each Workspace surface then needs two services enabled: the product API and its MCP service. Enabling the Gmail API alone is not enough. Enable all ten under APIs & Services → Library, or in one command:

gcloud services enable \
  gmail.googleapis.com gmailmcp.googleapis.com \
  drive.googleapis.com drivemcp.googleapis.com \
  calendar-json.googleapis.com calendarmcp.googleapis.com \
  chat.googleapis.com chatmcp.googleapis.com \
  people.googleapis.com \
  --project=PROJECT_ID

The People MCP surface is served by people.googleapis.com itself, so it has no separate MCP service. Confirm all ten landed:

gcloud services list --enabled --project=PROJECT_ID | grep -iE "gmail|drive|calendar|chat|people"

Configure consent and publish scopes

Consent settings live under Google Auth Platform, split across three screens:

• Branding – set an app name your users will recognize on the consent screen, plus a user support email. Check that the project picker shows the project you just created.
• Audience – choose Internal if every user is in your Workspace organization. Internal apps skip Google's verification review entirely, which is the fastest path and the recommended one. Choose External only if you need to connect accounts outside your organization. While an app is in Testing, only listed test users can connect, so publish it when you are ready for the whole organization.
• Data Access – click Add or remove scopes and add all 28 scopes listed under Required scopes. If a scope is not in the list, paste it into Manually add scopes. Click Add to table, then Update, then Save.

Several of these scopes are marked Sensitive or Restricted by Google. For an Internal app you can add them and continue. For an External app, Google requires verification before the app leaves testing, and the restricted Gmail and Drive scopes trigger a security assessment, so budget weeks rather than days.

Create the OAuth client

Under Google Auth Platform → Clients, click Create client:

• Application type – Web application
• Name – your preferred name, for example Agent Authority
• Authorized redirect URIs – click Add URI and paste the Redirect URI from the form in the Agent Authority console, using the Copy button next to it

Click Create. Google shows the Client ID and Client secret once, so copy both now.

3. Trust the client in your Workspace tenant

Two settings on the Workspace side gate the connection. Both need the Client ID from step 2.

Trust the OAuth client in the Admin console

Workspace classes these scopes as sensitive and restricted, so admin policy blocks them regardless of what an individual user consents to until the OAuth client is trusted. One trust covers all five products, because they share one client.

In the Google Admin console, go to Security → Access and data control → API controls → App access control. Click Add app → OAuth App Name or Client ID, enter the Client ID, select the app, and set access to Trusted.

If the setting shows a per-organizational-unit Overridden status, confirm the connecting user's org unit is covered, or set Trusted at the org root. Admin changes take a few minutes to propagate, so make one change, wait, then test once.

Configure the Chat app

The Chat tools need a Chat app configured in the same project. Under APIs & Services → Google Chat API → Configuration, set an app name and avatar, and leave interactive features disabled: the gateway calls the Chat API directly and does not receive Chat events. Without this configuration the four Chat tools return errors while the other 33 tools work normally.

4. Finish in the console

Back on the Google Workspace form in the Agent Authority console, paste the Client ID and Client Secret. Leave Token Endpoint Authentication on Auto-detect. Then click Add.

The resource is added with all tools and scopes pre-configured, and an Admin setup required dialog appears with a Setup guide button linking back to this page.

Verify the connection

The gateway syncs the Google Workspace tools automatically. To check the connection end to end, ask your agent to run a request:

Show my Google Workspace profile

If your name and email come back, the connection is working.

How users connect

Access is per user. Each additional user connects their own Google account the first time their agent calls a Google Workspace tool: the gateway returns a sign-in link, the user authorizes once, and the tools work from then on. Go to Connections to manage linked accounts.

Each user's own Workspace permissions control what they can reach. The gateway does not widen access beyond what the authenticated user could already do in Google Workspace.

Available tools

All 37 tools below ship with the catalog entry, so they appear in tool lists and policy pickers as soon as the resource is installed. Each tool is routed to the Google MCP server that serves it, and the live tool definitions are refreshed from those servers when the first user connects.

Gmail

Gmail has no send tool. Agents can draft mail, and a person sends it from Gmail.

Drive

Calendar

Chat

People

Required scopes

Add all 28 to the OAuth consent screen under Data Access, in step 2. This is the same list the gateway sends in the authorize request. All except the three identity scopes take the https://www.googleapis.com/auth/ prefix.

Identity – openid, email, profile

Gmail – gmail.modify, gmail.readonly, gmail.compose, gmail.labels

Drive – drive, drive.readonly, drive.file

Calendar – calendar, calendar.readonly, calendar.events, calendar.events.readonly, calendar.events.freebusy, calendar.freebusy, calendar.calendarlist, calendar.calendarlist.readonly

Chat – chat.spaces.readonly, chat.messages.readonly, chat.messages.create, chat.memberships.readonly, chat.users.readstate.readonly

People – contacts.readonly, contacts.other.readonly, directory.readonly, userinfo.profile, userinfo.email

The set is deliberately narrower than what Google offers. It excludes https://mail.google.com/ (permanent deletion), the Gmail settings scopes (mail forwarding and delegation), gmail.send, the Chat space and membership write scopes, and contact write access, none of which any shipped tool needs. It also excludes gmail.metadata: a token carrying that scope is forced into metadata-only mode by the Gmail API even when fuller read scopes are granted, which breaks message search and message bodies.

Scopes are requested at connect time, so a user's consent screen lists exactly the access above. Narrowing further is possible by removing tools, but a scope removed while its tool ships means that tool fails at call time.

Policy examples

Rules are evaluated top to bottom and the first match wins. Allow rules on their own restrict nothing – your org starts with a seeded Allow all rule, so any tool your allows don't cover still falls through to it. A restrictive recipe needs a catch-all deny scoped to this resource, ordered below the allows. New rules are inserted at the top of the list, so create them in reverse order or drag them into place. See Policies.

• Read-only access. Allow search_*, get_*, list_*, and read_*, then deny * below them.
• Block anything that leaves the org. Deny send_message and create_draft above any allow rules.
• Block destructive operations. Deny delete_event, apply_sensitive_thread_label, and apply_sensitive_message_label.
• Mail triage without calendar changes. Allow search_threads, get_thread, get_message, and *_label*, then deny *_event, then deny *.
• Drive reads but no writes. Allow search_files, list_recent_files, get_file_*, and read_file_content, then deny create_file, copy_file, and download_file_content.
• Allow full access for a specific agent. Scope an allow rule for * to that agent on this MCP server.

Tool patterns are case-sensitive and match exactly unless they contain *, so the lowercase snake*case patterns above (get*_, not Get_) are what match Google Workspace tool names.

Next steps

• Create a policy – start from the read-only pattern in Policy examples above.
• Connections – manage the Google accounts your users have linked.