Google Docs Managed MCP Server
Connect agents to Google Docs so they can read a document as Markdown, create documents, and make targeted edits to existing ones. The server can act as each calling user or as one shared service account, and it stays read-only until you allow writes.
After reading this page, you will be able to:
-
Choose between per-user OAuth and a service account for the Google Docs server
-
Set up Google Cloud access and create the Google Docs managed MCP server
-
Read a document and edit it from the Inspector
| The Google Docs managed MCP server is in Preview. If you don’t see Google Docs in the marketplace picker, contact Redpanda support. |
What this MCP server does
The Google Docs managed type calls the Google Docs API directly. It exposes these tools:
| Tool | What it does |
|---|---|
|
Read a document, every tab or the one in |
|
Create a document with a |
|
Replace, delete, insert, or format text in one tab of a document. Each edit finds its place by exact text. Up to 100 edits per call, and all of them apply together or not at all. When |
Keep these behaviors in mind:
-
Document arguments take an ID or a URL. Pass a document ID or a
docs.google.comdocument URL. A published link, which contains/d/e/, doesn’t hold a document ID. -
A truncated read is incomplete. When
truncatedistrue, the content was cut atmax_chars. Raisemax_chars, or read one tab at a time withtab_id. -
Reads cover tab bodies and footnotes. Headers and footers aren’t returned, and an image comes back as a placeholder, not as its content.
-
Pending suggestions are left out by default. Set
suggestionstoSUGGESTIONS_INLINEto mark suggested insertions as{inserted}and deletions as{--deleted--}. This setting needs edit access to the document. SetsuggestionstoSUGGESTIONS_ACCEPTEDto read the document as if every suggestion were accepted. -
Search, comments, and approvals belong to the Google Drive server. To search for documents or read their comments and approvals, use the Google Drive 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 Docs 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 | Which documents the server reaches | Use it for |
|---|---|---|
User OAuth |
The documents each calling user can open in Google Docs, with that user’s own Google token from the token vault |
Agents that act for a person. Google’s own sharing applies per user, edits carry that user’s name, and a new document lands in that user’s My Drive. |
Service account |
Only the documents that someone shared with the service account’s email address |
Agents with no person behind them, such as agents run by a trigger, that read or edit a known set of documents. This mode can’t create documents, because a service account has no My Drive. |
Service account with a |
The documents 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 documents, or that create documents. Every caller reaches that user’s documents, 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 document comes from Google’s sharing settings.
Enable the Google Docs API
Enable the Google Docs 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 docs.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 sensitive 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_DOCS_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-docs. 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_DOCS_CLIENT_SECRET. -
Under
Scopes, click Add scope and add the scope you chose, for examplehttps://www.googleapis.com/auth/documents.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. The Google Docs API also accepts the Drive scopes: https://www.googleapis.com/auth/drive.readonly for get_document, and https://www.googleapis.com/auth/drive for every tool. If your organization already has a provider that grants one of them, you can set this server’s Required Scopes to that scope instead. A Drive scope grants access to the user’s whole Drive, so use the Docs scopes for a new provider.
|
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-docs --project=<project-id> -
Create a JSON key for it:
gcloud iam service-accounts keys create adp-docs-key.json \ --iam-account=adp-docs@<project-id>.iam.gserviceaccount.com -
Store the whole key file in the Agentic Data Plane secret store under an
UPPER_SNAKE_CASEID, for exampleGOOGLE_DOCS_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 documents in one of these ways:
-
Share each document with the service account’s email address,
adp-docs@<project-id>.iam.gserviceaccount.com, the way you share with a person. Grant Viewer to read, or Editor to edit. -
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/documents.readonly scope, or https://www.googleapis.com/auth/documents 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, which it needs in order to create documents, 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-docs@<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/documents.readonly, orhttps://www.googleapis.com/auth/documentswhenAllow 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 documents 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 Docs card in the marketplace picker.
-
Replace the suggested
Name, and optionally add aDescription. -
Optional: Turn on
Allow Writesto add thecreate_documentandedit_documenttools. 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. -
Under
Auth, select one mode:-
User OAuth: SetProvider Nameto the provider you created, for examplegoogle-docs. UnderRequired Scopes, addhttps://www.googleapis.com/auth/documents.readonly, orhttps://www.googleapis.com/auth/documentswhenAllow Writesis on. -
Service Account: SetKey Secret Refto the secret that holds the key, for exampleGOOGLE_DOCS_SA_KEY.
-
-
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/documents in the server’s Required Scopes and in the provider’s Scopes.
Configure from the CLI
You need rpk ai 0.2.112 or later to create this server from the CLI. 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-docs \
--enabled \
--description "Google Docs with per-user OAuth" \
--managed.config '{
"@type": "type.googleapis.com/redpanda.mcps.google_docs.v1.GoogleDocsMCPConfig",
"allowWrites": false,
"userOauth": {
"providerName": "google-docs",
"requiredScopes": ["https://www.googleapis.com/auth/documents.readonly"]
}
}'
For a service account, replace the userOauth object with "serviceAccount": {"keySecretRef": "GOOGLE_DOCS_SA_KEY"}. To act as a Google Workspace user, also add "subject": "user@example.com".
Connect your Google account and read a document
-
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
get_documentwith the ID or URL of a document the identity can open:{"document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd", "format": "FORMAT_OUTLINE"}The result lists the document’s tabs, each with its headings as
content. See Test an MCP Server’s Tools with the Inspector.
To run the same call from the CLI, use rpk ai mcp-server tools call. See Test from the CLI.
rpk ai mcp-server tools call google-docs get_document \
--args '{"document":"1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd","format":"FORMAT_OUTLINE"}'
Edit a document
With Allow Writes on, edit_document changes a document without rewriting it. Each edit names the exact text it applies to, so read the document as plain text first:
-
Run
get_documentwithformatset toFORMAT_TEXT, and keep therevision_idfrom the result. -
Run
edit_documentwith thatrevision_idand a list ofedits:{ "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd", "revision_id": "<revision-id>", "edits": [ {"replace": {"find": "Retention is 30 days", "replacement": "Retention is 90 days"}}, {"insert": {"after": "Decision", "markdown": " (see the [runbook](https://example.com/runbook))"}}, {"format": {"find": "Release plan", "paragraph_style": {"named_style_type": "HEADING_2"}}} ] }
Each edit is one of three operations:
-
replace: Replace the text infindwithreplacement. An emptyreplacementdeletes the text. -
insert: Addtextormarkdownrightafterorbeforean exact piece of text, or at the end of the tab withat_end. -
format: Apply atext_style(bold, italic, strikethrough, underline, monospace, a link, or colors) to the matched text, or aparagraph_style(a named style such asHEADING_2, an alignment, or a list type) to whole paragraphs.
Keep these rules in mind:
-
Matches are exact and unique. The text in
find,after, orbeforeis case-sensitive and must occur exactly once in the tab. Forreplaceandformat, setall_occurrencesto change every match. A match can span paragraphs but not table cells. -
Edits don’t see each other. Every edit matches the document as it was before the call, so one edit can’t match text that another edit creates, and edits can’t overlap.
-
Plain text stays literal. The server never reads
replacementortextas Markdown. To write formatted content, use themarkdownfield ofreplaceorinsertinstead. -
The revision guards the edit. When you pass
revision_id, the edit fails if the document changed after that read. Read the document again, then retry. -
Pending suggestions block edits. The server refuses to edit a document that has pending suggestions. Accept or reject them in Google Docs first. The server’s own edits are direct edits, not suggestions.
-
Images come from public URLs. A Markdown image must use a public HTTPS URL, which Google fetches. The server doesn’t upload files.
If create_document fails after Google created the document, the error names the new document’s ID. Check that document before you create another one.
Troubleshooting
| Symptom | What to check |
|---|---|
An error that contains |
The Google Docs API isn’t enabled on the project that owns the OAuth client or the service account. See Enable the Google Docs API. |
An error that ends with |
The identity can’t open the document. With user OAuth, check that the calling user can open the document in Google Docs. With a service account, share the document 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 document: Viewer to read, or Editor to edit. Also check the scope, as in the previous row, and that the Google Docs API is enabled. See Enable the Google Docs API. |
|
|
|
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. |
|
The |
|
The document changed after the read that returned |
|
The document has pending suggestions. Accept or reject them in Google Docs, then retry. |
|
The text in |
|
The text in |
|
The text in |
An error that ends with |
The Google Docs 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. |
|
Your |