Google Workspace

Google Workspace is Google's productivity suite. The Willow connector works across Drive, Docs, Sheets, and Slides from a single MCP server: it searches and copies Drive files, reads and edits documents, spreadsheets, and presentations, and manages comments and sharing.

If you only need one of these products, the single-product connectors ask for fewer scopes: Google Drive, Google Sheets, and Google Slides. To administer the tenant itself, its users, groups, org units, and devices, use Google Workspace Admin instead.

Authentication types

Google Workspace supports three authentication methods:

• OAuth: Create your own Google Cloud OAuth app. You control the app, scopes, and credentials. Each user connects with their Google account. Use this method for production. Google Cloud setup is required.

• Instant OAuth: Use Willow's preconfigured Google app. Setup is faster, but fewer scopes are available. Use this method for testing, not production. No Google Cloud setup is required.

• Server App: Use a Google Cloud service account. No user signs in; the service account acts on behalf of a user you name. Reaching user data requires domain-wide delegation, which only a Google Workspace super admin can grant. See Setting up a Server App.

Before you start

You will need:

• A Google account that can create projects in the Google Cloud Console. A personal Gmail account is enough for testing OAuth.
• Your Willow Redirect URL (see Create the OAuth client).

If your company uses Google Workspace, your admin may block third-party apps by default. In that case a Workspace super admin has to allow your app before anyone can connect. See Approving the app for your organization.

Order matters

Enable the four APIs before you pick scopes. The scope picker only lists scopes for APIs that are already enabled in the project, so if you skip ahead you will not be able to find the Drive, Docs, Sheets, and Slides scopes.

The default Drive scope is restricted

Willow selects https://www.googleapis.com/auth/drive by default, and Google classifies it as restricted, its strictest tier. Publishing an External app with it requires OAuth verification and an annual third-party security assessment (CASA). See Check how Google classifies your scopes.

Setting up OAuth

1. Create or select a project

Go to https://console.cloud.google.com/ and either create a new project or select an existing one using the project picker in the top bar.

Every step below applies to the selected project, so make sure the right project name is showing before you continue.

2. Enable the Workspace APIs

Go to APIs & Services → Library. Search for each of these APIs, open it, and click Enable:

API	Direct link
Google Drive API	drive.googleapis.com
Google Docs API	docs.googleapis.com
Google Sheets API	sheets.googleapis.com
Google Slides API	slides.googleapis.com

Once an API is on, its page shows API Enabled and a Manage button instead of Enable:

Enable all four even if you only plan to use some of the tools. A tool whose API is disabled fails with ... API has not been used in project ... before or it is disabled.

3. Configure the consent screen (Branding)

Google now places OAuth settings under Google Auth Platform instead of the old "OAuth consent screen" wizard. Open console.cloud.google.com/auth/branding. You can also go to APIs & Services → OAuth consent screen, which redirects to the same page.

Fill in the required fields:

• App name: What users see on the Google consent screen
• User support email
• Developer contact email

Click Save. Until these fields are filled in, the Audience page will warn that your OAuth configuration is incomplete.

First time in Google Auth Platform

If the project has never had OAuth configured, the Branding page shows Google Auth Platform not configured yet. Click Get started. Google walks you through App Information (app name and support email), Audience, Contact Information, and Finish, where you agree to the Google API Services User Data Policy, then click Create. After that, the Branding, Audience, and Data Access pages open normally.

The Audience you pick in the wizard is the same setting described in step 4.

4. Choose your audience

Open Audience (console.cloud.google.com/auth/audience) and set the User type.

Use Internal if you can. Click Make internal. An Internal app can be used only by members of your organization and does not need Google's External app verification.

Google offers Internal only when the Google Cloud project belongs to a Google Cloud Organization. Google Workspace or Cloud Identity provides an organization, but a personal Gmail account does not. If your project has no organization, Make internal is greyed out and External is your only option.

Internal apps may still need admin approval

An Internal app may still need admin approval for restricted Google Workspace services, including Gmail and Drive. See Approving the app for your organization.

If you use External, the app starts in Testing. Only accounts listed under Test users can connect. Add each user under Test users → Add users. Anyone who is not on the list gets an error when they try to connect.

Two things to know about Testing before you rely on it:

• The cap is 100 test users over the entire lifetime of the project. It cannot be reset or changed. Each person counts toward the limit as soon as you add them, even if they never connect.
• The user's authorization and refresh token expire after seven days. Users will have to reconnect every week.

Adding a test user takes effect immediately. Until the account is on the list, Google returns Error 403: access_denied with the message "Access blocked: … has not completed the Google verification process". Although the message mentions verification, it usually means the account is missing from Test users.

Complete Branding before publishing. If the Branding page is incomplete, the Audience page shows "Your app's OAuth configuration is incomplete" and Publish app stays greyed out.

5. Add Google Workspace scopes

Open Data Access (console.cloud.google.com/auth/scopes) and click Add or remove scopes.

When you create the connector, Willow selects these four scopes, one per product:

Scope	Grants
https://www.googleapis.com/auth/drive	See, edit, create, and delete all of the user's Google Drive files
https://www.googleapis.com/auth/documents	See, edit, create, and delete all of the user's Google Docs documents
https://www.googleapis.com/auth/spreadsheets	See, edit, create, and delete all of the user's Google Sheets spreadsheets
https://www.googleapis.com/auth/presentations	See, edit, create, and delete all of the user's Google Slides presentations

The quickest way to add them is to paste all four URIs, separated by commas, into Manually add scopes at the bottom of the panel and click Add to table. They appear checked at the top of the table. Click Update, then Save on the Data Access page.

Willow's connector also offers narrower scopes. Pick these instead of the defaults if the tools you enable do not need full read-write access:

Scope	Use it when
https://www.googleapis.com/auth/drive.readonly	Tools only read Drive files.
https://www.googleapis.com/auth/drive.file	Tools only touch files the app creates or the user opens with it.
https://www.googleapis.com/auth/drive.metadata.readonly	Tools only read file metadata, not file contents.
https://www.googleapis.com/auth/drive.metadata	Tools read and change file metadata.
https://www.googleapis.com/auth/drive.appdata	Tools use the app's hidden Drive data folder.
https://www.googleapis.com/auth/drive.apps.readonly	Tools list the user's installed Drive apps.
https://www.googleapis.com/auth/drive.photos.readonly	Tools read Google Photos content stored in Drive.
https://www.googleapis.com/auth/drive.meet.readonly	Tools read Drive files created by Google Meet.
https://www.googleapis.com/auth/drive.scripts	Tools change the behavior of Apps Script projects.
https://www.googleapis.com/auth/drive.labels.readonly	You use the Drive label conditions.
https://www.googleapis.com/auth/documents.readonly	Tools only read Docs.
https://www.googleapis.com/auth/spreadsheets.readonly	Tools only read Sheets.
https://www.googleapis.com/auth/presentations.readonly	Tools only read Slides.

Tools that write, such as Create Google Sheet, Insert Text Doc, or Share File, fail with a 403 under a read-only scope.

Check how Google classifies your scopes

After you save, the Data Access page groups each scope by how sensitive Google considers it. With the four defaults, documents, spreadsheets, and presentations land under Your sensitive scopes, and drive lands under Your restricted scopes.

Group	What it means for you
Sensitive	An External app must pass Google's OAuth verification before you can publish it. Internal apps and apps that remain in Testing do not need this verification.
Restricted	Verification, plus an annual third-party security assessment (CASA), for External apps that are published.

If you want to avoid the restricted tier, replace drive with a narrower Drive scope and confirm the Data Access page no longer lists anything under Your restricted scopes.

6. Create the OAuth client

Open Clients (console.cloud.google.com/auth/clients) and click Create client.

1. Set Application type to Web application
2. Give the client a name
3. Under Authorized redirect URIs, click Add URI and add your Willow redirect URL:
   • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
   • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback
4. Click Create
5. Copy the Client ID and Client Secret

The redirect URI must match exactly, including https://, and must not have a trailing slash. A mismatch produces Error 400: redirect_uri_mismatch when you connect.

7. Finish in Willow

Open your Google connector in Willow and go to the Setup tab.

1. Under Authentication, select OAuth to use your own Client ID and Client Secret.
2. Paste the Client ID and Client Secret
3. Confirm the Redirect URL shown here exactly matches the URI you registered in step 6
4. Under Scopes, click Add and select the same scopes you configured in step 5
5. Click Save Changes

Selecting a scope in Willow that you did not add in Google Cloud will fail at connect time, so keep the two lists identical.

One OAuth client can serve several connectors

Every connector in a Willow organization shares the same Redirect URL, so one Google OAuth client works for all of them. You do not need one client per connector. Paste the same Client ID and Secret into each connector, then select only the scopes it needs.

Select the narrowest scopes offered by the connector that meet your needs.

8. Authorize the connection

Click Check connection. It stays disabled until the credentials are saved.

Willow opens Google's consent window. It also shows an Authenticate your MCP dialog with the authorization URL and an Authenticate button in case your browser blocks the window. Complete the Google consent steps, then click I've authenticated.

"Google hasn't verified this app"

An External app that requests sensitive or restricted scopes may show an unverified-app warning. If you are testing your own app, follow the available prompts to continue to consent. Publishing the app does not by itself complete verification.

If the consent window does not appear, use the Authenticate button in the dialog.

Test a read-only tool

To test the connection, go to the Tools tab, open the row menu for a read-only tool, and choose Test Tool → Run test. A successful run returns data from Google as JSON.

Use an existing resource that the authenticated account can access. A 401 response indicates an authentication problem; a 403 or 404 can also indicate missing permissions or an inaccessible resource, so an error alone does not confirm a working connection.

Check Guards if a response is blocked

If a tool returns Tool blocked by organization's guardrails, check the matching Willow Guard. The response was blocked by a Guard; changing OAuth scopes will not fix that block.

For example, run Google Drive Search with this input:

{ "query": "trashed = false", "pageSize": 3, "fields": "files(id,mimeType)" }

query is required. A successful run lists up to three Drive files the authenticated account can see. Add name to fields if you want file names in the response.

Approving the app for your organization

Google Workspace admins can restrict which third-party apps may access organization data. When this restriction is on, users may see an access-blocked message naming their Workspace admin or an admin-policy error, even when the OAuth setup is correct.

A Workspace super admin fixes this in the Admin console. From the Admin console, go to Menu → Security → Access and data control → API controls, then click Manage App Access.

To add an app that is not listed yet:

1. Click Configure new app
2. Enter the app name or the Client ID from step 6, then click Search
3. Select the app and click Continue
4. Under Access to Google data, choose Specific Google data and allow the scopes your connector needs, including any required Google Sign-in scopes. Choose Trusted only if your organization intends to allow the app to request all Google services, including restricted services.
5. Click Continue, then Finish

To change an app that is already listed, point to it and click Change access. To update several apps, select them and click Change access at the top. Use Select org units → Include organizations to choose which parts of your organization receive the change. Leave the top-level organization selected to apply it to everyone. Then confirm with Change access.

The access levels are Trusted, Limited, Specific Google data, and Blocked. Specific Google data permits the scopes you approve, including scopes for restricted services. Trusted permits access across all services.

Internal apps also need approval if your organization restricts unconfigured third-party apps. See Google's guide, Control which third-party & internal apps access Google Workspace data.

Setting up a Server App (Service Account)

A service account lets Willow call Google without a user signing in. It has no Drive, Docs, Sheets, or Slides data of its own, so to reach a user's files a Workspace super admin must grant it domain-wide delegation and Willow must impersonate a user in that domain. Personal Gmail accounts cannot use domain-wide delegation.

1. Create the service account

1. In the same Google Cloud project, confirm the four APIs from step 2 are enabled.
2. Go to Menu → IAM & Admin → Service Accounts and click Create service account.
3. Enter a display name, then click Done. You can skip Create and continue: IAM roles only grant access to Google Cloud resources, not to Workspace data such as Drive files or Sheets.

2. Create a JSON key

1. On the Service Accounts page, click the service account's email address.
2. Open the Keys tab, click Add key → Create new key, select JSON, and click Create.

Google downloads the key file once. Store it securely and never commit it to version control.

3. Copy the client ID

On the service account's page, click Show advanced settings. Under Domain-wide delegation, copy the service account's Client ID. It is also the client_id value in the JSON key file.

4. Authorize domain-wide delegation

A Workspace super admin must do this step.

1. In the Admin console, go to Menu → Security → Access and data control → API controls.
2. Click Manage Domain Wide Delegation, then Add new.
3. Paste the service account's Client ID.
4. In OAuth Scopes, enter each scope the connector needs, comma-separated. For the four defaults: https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/presentations
5. Click Authorize.
6. Point to the new client ID, click View details, and confirm every scope is listed.

Google notes that changes can take up to 24 hours but typically apply sooner. If your organization has multi-party approval turned on, another super admin must approve the new authorization before it takes effect. See Google's guide, Control API access with domain-wide delegation.

5. Configure Server App in Willow

Open the connector's Setup tab, select Server App, and fill in the fields from the JSON key file:

• App ID: the service account's email, the client_email value (name@project-id.iam.gserviceaccount.com)
• Subject: the email of the Workspace user the service account acts as
• Scopes: the same scopes you authorized in step 4. A scope Willow requests but the admin did not authorize fails at token time.
• Private Key: the private_key value, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines

Click Save Changes, then test a read-only tool as described in Test a read-only tool.

Every call runs as the Subject user, so the connector sees exactly what that user can see in Drive.

Blocking sensitive Drive files

Google Workspace ships predefined conditions that check a Drive file's applied labels before a tool touches it, so access follows the classification your organization already maintains in Drive:

Condition	Effect
Block sensitive Drive files	Blocks files carrying any of the labels you select.
Block Drive files by label field value	Blocks files whose label field is set to a flagged value, for example Confidentiality = Confidential.

Both are designed for google-drive-get-file-metadata, google-drive-copy-file, and google-drive-convert-to-google-doc, and both require the https://www.googleapis.com/auth/drive.labels.readonly scope. Add it in Google Cloud and in Willow alongside the scopes above, otherwise the label lookup fails and, because conditions fail closed by default, every call to those tools is blocked.

Publishing and verification

If your app is Internal, you do not need External app verification or a test-user list, and authorizations do not expire after seven days.

An External app starts in Testing. Only listed test users can connect, and refresh tokens expire after seven days. To use the app in production, click Publish app on the Audience page. Google must verify an External app that requests sensitive scopes, and one that keeps the restricted drive scope must also complete an annual CASA security assessment. Submit it from the Verification Center. The review can take days or weeks.

Troubleshooting

Symptom	Cause
Required scopes missing from the scope picker	A required API is not enabled in the selected project. See step 2.
Error 400: redirect_uri_mismatch	The Redirect URI in the OAuth client does not exactly match Willow's Redirect URL.
org_internal error	The app is Internal, but the user does not belong to the organization that owns the Google Cloud project.
Error 403: access_denied: "Access blocked: <domain> has not completed the Google verification process… can only be accessed by developer-approved testers"	The app is External and in Testing, but the Google account is not in Test users. Add the account on the Audience page. This is a test-user error, not a Workspace admin approval error.
"Access blocked" that names your Workspace admin, or persists for an account already listed under Test users	Workspace admin has not trusted the app. See Approving the app for your organization.
Users have to reconnect every 7 days	App is External and still in Testing. Authorizations expire seven days after consent.
Make internal is greyed out	The project does not belong to a Google Cloud Organization
Publish app is greyed out, with "Your app's OAuth configuration is incomplete"	Branding is unfinished. Fill in the Branding page first.
Tool call returns {"error":{"type":"Tool Error","message":"Tool blocked by organization's guardrails"}}	A Willow Guard blocked the response. Check Guards for the matching rule and result.