Google Drive Managed MCP Server
Connect agents to Google Drive so they can find files, read their content, and check who commented on or approved them. The server works on Google Docs, Sheets, and Slides files and on any other file in Drive, and it can act as each calling user or as one shared service account.
After reading this page, you will be able to:
-
Choose between per-user OAuth and a service account for the Google Drive server
-
Set up Google Cloud access and create the Google Drive managed MCP server
-
Read a file’s comments and approvals from the Inspector
What this MCP server does
The Google Drive managed type calls the Google Drive API directly. It exposes these tools:
| Tool | What it does |
|---|---|
|
Find files with a query in Google’s Drive search syntax. Optional arguments: |
|
Return a file’s content. For a Google Docs, Sheets, or Slides file, the server exports the file to the MIME type in |
|
Return a file’s ID, name, MIME type, description, link, creation and modification times, version, size, owners, last modifying user, shared drive ID, and whether the caller can edit or comment. |
|
Return a file’s comment threads with their replies, quoted text, authors, timestamps, and resolution state. Optional arguments: |
|
Return a file’s approvals, which are the formal sign-offs that users request with File > Approvals in Google Docs, Sheets, and Slides. Each approval holds its status, its reviewers and their decisions, and what happens to the approval when the file changes. |
|
Add a comment to a file, with optional |
|
Reply to a comment thread. To resolve or reopen the thread, set |
Keep these behaviors in mind:
-
File arguments take an ID or a URL. Every tool except
searchaccepts a file ID or the URL of a Docs, Sheets, Slides, or Drive file. A published link, which contains/d/e/, doesn’t hold a file ID. Use the file’s edit or view link instead. -
Downloads have a size limit. A
downloadcall fails when the content is larger than 10 MiB. The server never returns part of a file. Google also limits the size of an exported Google Workspace file. -
The server doesn’t change file content or approvals. It can’t create, edit, move, share, or delete files, and it can’t start, approve, decline, or cancel an approval. With
Allow Writeson, it can add comments and replies. To read and edit the text of a Google Docs document, use the Google Docs managed MCP server.
Prerequisites
-
A Google Cloud project where you can enable APIs and create OAuth clients or service accounts. The project runs no compute, because AI Gateway calls the Google Drive API over HTTPS. Your Agentic Data Plane environment doesn’t need to run on Google Cloud.
-
The
gcloudCLI, signed in to that project. See Install the gcloud CLI. -
Permission in Agentic Data Plane to create secrets, OAuth providers, and MCP servers.
-
For per-user OAuth, familiarity with user-delegated OAuth.
-
For a service account that acts as a Google Workspace user, a Google Workspace super administrator who can authorize domain-wide delegation.
Choose how the server authenticates
The server supports per-user OAuth and a service account. A service account can act as itself or as one Google Workspace user:
| Mode | Whose files the server reaches | Use it for |
|---|---|---|
User OAuth |
The files each calling user can open in Google Drive, with that user’s own Google token from the token vault |
Agents that act for a person. Google Drive’s own sharing applies per user, and comments an agent adds carry that user’s name. |
Service account |
Only the files, folders, and shared drives that someone shared with the service account’s email address |
Agents with no person behind them, such as agents run by a trigger, that work on a known set of files. Every caller reaches the same files. |
Service account with a |
The files that one Google Workspace user can open. The service account acts as that user through domain-wide delegation. |
Agents with no person behind them that need one user’s view of Drive. Every caller reaches that user’s files, so limit who can call the server. |
Whichever mode you choose, the Google identity needs no Identity and Access Management (IAM) role. Access to a file comes from Google Drive sharing.
Enable the Google Drive API
Enable the Google Drive API on the Google Cloud project that owns the credential, which is the project where you create the OAuth client or the service account. Replace <project-id> with your project ID:
gcloud services enable drive.googleapis.com --project=<project-id>
Set up per-user OAuth
If you use a service account, skip this section.
Create the OAuth client
| This configuration refers to a third-party product. Specific UI elements may not be up to date. |
The server needs one of these Google OAuth scopes:
| Scope | Use it when |
|---|---|
|
|
|
|
Google classifies both as restricted scopes. An app whose audience is Internal doesn’t need Google’s verification. An External app that requests them shows users an unverified app warning until Google verifies it.
-
In the Google Auth Platform for the project where you enabled the API, configure the consent screen:
-
On the Branding page, give the app a name your users recognize, for example
Redpanda Agentic Data Plane. -
On the Audience page, choose Internal so only users in your Google Workspace organization can connect. If Internal isn’t available, choose External and add each user as a test user.
-
On the Data Access page, add the scope from the table.
-
-
Open Clients and create a client with Application type set to Web application.
-
Under Authorized redirect URIs, add the AI Gateway OAuth callback for your environment:
https://aigw.<cluster-id>.clusters.rdpa.co/oauth/v1/callbackReplace
<cluster-id>with your cluster’s identifier. If you’re not sure of the exact URL, add it later. The OAuth provider you create in Configure the OAuth provider shows it on its detail page. -
Copy the client’s Client ID and Client secret.
For the full procedure, see Google’s Configure the OAuth consent screen and choose scopes guide.
Store the client secret
Store the client secret in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE ID, for example GOOGLE_DRIVE_CLIENT_SECRET, with the Single line value format. See Create a secret.
Configure the OAuth provider
Register a OAuth provider for Google in Agentic Data Plane. See Configure an OAuth Provider for the full form.
-
Open Integrations setup in the sidebar and click the Outbound providers tab.
-
Click Add provider, then choose the Google preset.
The preset fills in Google’s authorization, token, and revocation endpoints, the
openid,email, andprofilescopes, PKCE, and the Client Secret (POST) authentication method. It also requests offline access, so each user’s connection gets a refresh token and doesn’t expire after an hour. -
Set
Name, for examplegoogle-drive. You reference the provider by this name when you create the server. -
Enter the
Client IDfrom the Google client, and setClient secret referenceto the secret, for exampleGOOGLE_DRIVE_CLIENT_SECRET. -
Under
Scopes, click Add scope and add the scope you chose, for examplehttps://www.googleapis.com/auth/drive.readonly. -
Click Create provider.
If you haven’t added the callback URL to the Google client yet, copy the Authorization callback URL from the provider’s detail page and add it under the client’s Authorized redirect URIs.
One Google OAuth provider can serve several Google servers, so each user connects their Google account once. Add every scope those servers require to the provider’s Scopes. Google’s Docs and Sheets APIs also accept the Drive scopes, so a provider that grants https://www.googleapis.com/auth/drive can serve the Google Drive, Google Docs, and Google Sheets servers when you set each server’s Required Scopes to that scope. The scope grants access to the user’s whole Drive, so grant it only when a server needs it.
|
Set up a service account
If you use per-user OAuth, skip this section.
| This configuration refers to a third-party product. Specific UI elements may not be up to date. |
-
Create a service account. Replace
<project-id>with your project ID:gcloud iam service-accounts create adp-drive --project=<project-id> -
Create a JSON key for it:
gcloud iam service-accounts keys create adp-drive-key.json \ --iam-account=adp-drive@<project-id>.iam.gserviceaccount.com -
Store the whole key file in the Agentic Data Plane secret store under an
UPPER_SNAKE_CASEID, for exampleGOOGLE_DRIVE_SA_KEY, with the Multiline value format. See Create a secret. -
Delete the local key file once the secret is stored.
-
Give the service account access to files in one of these ways:
-
Share each file, folder, or shared drive with the service account’s email address,
adp-drive@<project-id>.iam.gserviceaccount.com, the way you share with a person. Grant Viewer to read, or Commenter to add comments and replies. -
Let the service account act as a Google Workspace user. See Authorize domain-wide delegation.
-
AI Gateway exchanges the key for short-lived access tokens and checks the key when the server starts. The server requests the https://www.googleapis.com/auth/drive.readonly scope, or https://www.googleapis.com/auth/drive when Allow Writes is on. You don’t set scopes for a service account in Agentic Data Plane.
Authorize domain-wide delegation
To make the service account act as one Google Workspace user, a super administrator authorizes it for domain-wide delegation:
-
Find the service account’s client ID. It’s the
client_idvalue in the key file. If you deleted the key file, look it up:gcloud iam service-accounts describe adp-drive@<project-id>.iam.gserviceaccount.com \ --format="value(oauth2ClientId)" -
In the Google Admin console, go to Security > Access and data control > API controls, and click Manage Domain Wide Delegation.
-
Click Add new, and enter the client ID.
-
Under OAuth scopes, enter the scope the server requests:
https://www.googleapis.com/auth/drive.readonly, orhttps://www.googleapis.com/auth/drivewhenAllow Writesis on. -
Click Authorize.
When you create the server, set Subject to that user’s email address. If you turn on Allow Writes later, authorize the drive scope too, because the server then requests it.
For the full procedure, see Google’s Control API access with domain-wide delegation guide.
Create the server
Before you start, finish Set up per-user OAuth or Set up a service account.
-
Open MCP servers in the sidebar.
-
Click Add MCP server.
-
Click the Google Drive card in the marketplace picker.
-
Replace the suggested
Name, and optionally add aDescription. -
Under
Auth, select one mode:-
User OAuth: SetProvider Nameto the provider you created, for examplegoogle-drive. UnderRequired Scopes, addhttps://www.googleapis.com/auth/drive.readonly, orhttps://www.googleapis.com/auth/drivewhenAllow Writesis on. -
Service Account: SetKey Secret Refto the secret that holds the key, for exampleGOOGLE_DRIVE_SA_KEY. If the form showsHeader Name, leave it empty, because the server doesn’t use it.
-
-
Optional: Turn on
Allow Writesto add theadd_commentandreply_to_commenttools. Leave it off for a read-only server. -
Optional, for a service account only: Set
Subjectto the email address of the Google Workspace user the service account acts as. Leave it empty to act as the service account itself. With user OAuth, the server ignoresSubject. -
Click Create server.
With user OAuth, each user’s connection must hold every required scope. A connection with fewer scopes returns scope_upgrade_required, and the user reconnects to grant the missing one. The consent screen asks for the server’s required scopes even when the OAuth provider’s Scopes don’t list them. Still add each required scope to the provider’s Scopes, because a connection that starts without the server’s required scopes requests the provider’s scopes instead.
Allow Writes doesn’t change the required scopes. When you turn it on, replace the read-only scope with https://www.googleapis.com/auth/drive in the server’s Required Scopes and in the provider’s Scopes.
Configure from the CLI
The allowWrites and subject fields need rpk ai 0.2.112 or later. Run rpk ai version to check your version. To update, run rpk ai upgrade.
To create a read-only server with per-user OAuth, pass the configuration as JSON in --managed.config:
rpk ai mcp-server create google-drive \
--enabled \
--description "Google Drive with per-user OAuth" \
--managed.config '{
"@type": "type.googleapis.com/redpanda.mcps.google_drive.v1.GoogleDriveMCPConfig",
"allowWrites": false,
"userOauth": {
"providerName": "google-drive",
"requiredScopes": ["https://www.googleapis.com/auth/drive.readonly"]
}
}'
For a service account, replace the userOauth object with "serviceAccount": {"keySecretRef": "GOOGLE_DRIVE_SA_KEY"}. To act as a Google Workspace user, also add "subject": "user@example.com".
Connect your Google account and test
-
With user OAuth, open the server in Agentic Data Plane. If a connection banner appears, click Connect, sign in to Google, and approve the consent screen.
If you call a tool before connecting, the call fails with a connection-required result that carries an authorization URL. That URL starts the same Google consent flow.
-
Open the server’s Inspector tab and run
searchwith a query:{"query": "name contains 'Launch plan'", "max_results": 5}The result lists the matching files. See Test an MCP Server’s Tools with the Inspector.
-
Run
get_filewith the ID or URL of one of the files:{"file_id": "https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd/edit"}
To run the search call from the CLI, use rpk ai mcp-server tools call. See Test from the CLI.
rpk ai mcp-server tools call google-drive search \
--args '{"query":"name contains '\''Launch plan'\''","max_results":5}'
A search covers only the identity’s own files and files shared with it, unless you set include_shared_drives to true. A service account that acts as itself has no files of its own, so set include_shared_drives when its files are in shared drives. If the result has incomplete_search set to true, Google couldn’t search every shared drive, and matching files may be missing.
Read comments and approvals
Agents can use list_comments and list_approvals to check whether a file was reviewed. For example, to read the threads that are still open on a file:
{"file_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd", "unresolved_only": true}
Keep these points in mind when an agent relies on comments:
-
Read every page.
list_commentsreads up tomax_commentsthreads in one call. When the result has anext_page_token, more threads remain, so call the tool again with the token aspage_token. The server appliesunresolved_onlyafter it reads the threads, so a page can hold no threads and still have anext_page_token. -
A failed read isn’t an empty result. If Google fails partway through, the whole call fails, and the server doesn’t return the threads it read so far.
-
Threads come back newest first. Google orders threads by creation time, and a new reply doesn’t move its thread. Replies come back oldest first.
-
Authors have a display name only. Google doesn’t return the email addresses of comment and reply authors. A display name isn’t a verified identity. The
mefield marks the caller’s own comments. -
Deleted replies stay in the thread. A deleted reply has
deletedset totrue, so don’t count it as a current sign-off. -
Comments don’t change the file’s version. A reply or a resolved thread can leave the
versionandmodified_timethatget_filereturns unchanged, so read the comments again before you act on them.
An approval is a separate record from a comment. list_approvals returns each approval’s status (in progress, approved, declined, or canceled), each reviewer’s decision, and content_change_behavior:
-
CONTENT_CHANGE_BEHAVIOR_RESET_APPROVAL: An edit while the approval is in progress resets the decisions already given, and Google locks an approved file. -
CONTENT_CHANGE_BEHAVIOR_NO_APPROVAL_ACTION: Edits don’t affect the approval, so the file may have changed after it was approved.
A file with no approvals can still have sign-offs in its comments, and a comment that says a file looks good isn’t an approval. When the result has a next_page_token, call list_approvals again with the token as page_token.
When Allow Writes is on, add_comment adds a comment on the whole file. Google shows quoted_text with the comment but doesn’t highlight that text in the file.
Troubleshooting
| Symptom | What to check |
|---|---|
An error that contains |
The Google Drive API isn’t enabled on the project that owns the OAuth client or the service account. See Enable the Google Drive API. |
An error that ends with |
The identity can’t open the file. With user OAuth, check that the calling user can open the file in Google Drive. With a service account, share the file with the service account’s email address, or set |
An error that ends with |
The connection doesn’t grant a scope the call needs. |
An error that ends with |
Google refused the call for this identity. Check that the identity has enough access to the file: Viewer to read, or Commenter to add comments and replies. Also check the scope, as in the previous row, and that the Google Drive API is enabled. See Enable the Google Drive API. |
|
A service account that acts as itself sees only what was shared with it. Share the files or the shared drive with its email address, and set |
|
The server has a |
|
Google refused the key, for example because it was deleted or the service account was disabled. Create a new key and update the secret. |
The server’s tools can’t be listed, and every call fails |
If the server uses a service account, check that the secret holds the whole service account JSON key file, stored with the Multiline value format. AI Gateway checks the key when the server starts. |
|
Your |
|
The |
|
The file’s content is larger than 10 MiB. Export a Google Workspace file to a smaller format with |
An error that ends with |
The Google Drive API quota for the project or the user is exhausted. Wait, then retry. |
|
The user hasn’t connected their Google account yet. Have the user open the server in Agentic Data Plane, click Connect, and approve Google’s consent screen. Later calls reuse the stored token. See user-delegated OAuth. |
|
The user’s connection lacks a scope the server requires. Have the user click Connect again and approve the consent screen, which asks for the missing scope. |
Users have to reconnect about every hour |
The OAuth provider doesn’t request offline access, so connections get no refresh token. Create the provider from the Google preset, which requests it. |
An error doesn’t include Google’s error message |
The server doesn’t pass Google’s own error message on. For a failed Google call, the error names the step that failed and the HTTP status code. It also includes Google’s error status and reason when Google sends them, and a short hint when the cause has a known fix. |