Agentic Data Plane
Preview

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

get_document

Read a document, every tab or the one in tab_id. The format argument selects Markdown (FORMAT_MARKDOWN, the default), plain text (FORMAT_TEXT), or a heading outline (FORMAT_OUTLINE). Optional arguments: suggestions and max_chars (1,000 to 5,000,000, default 200,000). The result holds the document’s ID, title, link, tabs, and, for a caller who can edit the document, a revision_id.

create_document

Create a document with a title and optional markdown content: headings, paragraphs, lists, inline formatting, links, tables, fenced code, and images. When Allow Writes is off, this tool isn’t available.

edit_document

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 Allow Writes is off, this tool isn’t available.

Keep these behaviors in mind:

  • Document arguments take an ID or a URL. Pass a document ID or a docs.google.com document URL. A published link, which contains /d/e/, doesn’t hold a document ID.

  • A truncated read is incomplete. When truncated is true, the content was cut at max_chars. Raise max_chars, or read one tab at a time with tab_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 suggestions to SUGGESTIONS_INLINE to mark suggested insertions as {inserted} and deletions as {--deleted--}. This setting needs edit access to the document. Set suggestions to SUGGESTIONS_ACCEPTED to 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 gcloud CLI, 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 Subject

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

https://www.googleapis.com/auth/documents.readonly

Allow Writes is off. This scope covers get_document.

https://www.googleapis.com/auth/documents

Allow Writes is on. Google accepts this scope for every tool.

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.

  1. In the Google Auth Platform for the project where you enabled the API, configure the consent screen:

    1. On the Branding page, give the app a name your users recognize, for example Redpanda Agentic Data Plane.

    2. 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.

    3. On the Data Access page, add the scope from the table.

  2. Open Clients and create a client with Application type set to Web application.

  3. Under Authorized redirect URIs, add the AI Gateway OAuth callback for your environment:

    https://aigw.<cluster-id>.clusters.rdpa.co/oauth/v1/callback

    Replace <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.

  4. 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.

  1. Open Integrations setup in the sidebar and click the Outbound providers tab.

  2. Click Add provider, then choose the Google preset.

    The preset fills in Google’s authorization, token, and revocation endpoints, the openid, email, and profile scopes, 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.

  3. Set Name, for example google-docs. You reference the provider by this name when you create the server.

  4. Enter the Client ID from the Google client, and set Client secret reference to the secret, for example GOOGLE_DOCS_CLIENT_SECRET.

  5. Under Scopes, click Add scope and add the scope you chose, for example https://www.googleapis.com/auth/documents.readonly.

  6. 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.
  1. Create a service account. Replace <project-id> with your project ID:

    gcloud iam service-accounts create adp-docs --project=<project-id>
  2. 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
  3. Store the whole key file in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE ID, for example GOOGLE_DOCS_SA_KEY, with the Multiline value format. See Create a secret.

  4. Delete the local key file once the secret is stored.

  5. 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:

  1. Find the service account’s client ID. It’s the client_id value 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)"
  2. In the Google Admin console, go to Security > Access and data control > API controls, and click Manage Domain Wide Delegation.

  3. Click Add new, and enter the client ID.

  4. Under OAuth scopes, enter the scope the server requests: https://www.googleapis.com/auth/documents.readonly, or https://www.googleapis.com/auth/documents when Allow Writes is on.

  5. 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.

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the Google Docs card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

  5. Optional: Turn on Allow Writes to add the create_document and edit_document tools. Leave it off for a read-only server.

  6. Optional, for a service account only: Set Subject to 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 ignores Subject.

  7. Under Auth, select one mode:

    • User OAuth: Set Provider Name to the provider you created, for example google-docs. Under Required Scopes, add https://www.googleapis.com/auth/documents.readonly, or https://www.googleapis.com/auth/documents when Allow Writes is on.

    • Service Account: Set Key Secret Ref to the secret that holds the key, for example GOOGLE_DOCS_SA_KEY.

  8. 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

  1. 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.

  2. Open the server’s Inspector tab and run get_document with 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:

  1. Run get_document with format set to FORMAT_TEXT, and keep the revision_id from the result.

  2. Run edit_document with that revision_id and a list of edits:

    {
      "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 in find with replacement. An empty replacement deletes the text.

  • insert: Add text or markdown right after or before an exact piece of text, or at the end of the tab with at_end.

  • format: Apply a text_style (bold, italic, strikethrough, underline, monospace, a link, or colors) to the matched text, or a paragraph_style (a named style such as HEADING_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, or before is case-sensitive and must occur exactly once in the tab. For replace and format, set all_occurrences to 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 replacement or text as Markdown. To write formatted content, use the markdown field of replace or insert instead.

  • 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 SERVICE_DISABLED

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 file does not exist or is not shared with the caller

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 Subject to a user who can open it.

An error that ends with the credential lacks a scope this call needs

The connection doesn’t grant a scope the call needs. create_document and edit_document need https://www.googleapis.com/auth/documents. With user OAuth, set the server’s Required Scopes to that scope, add it to the OAuth provider’s Scopes, and have the user click Connect again.

An error that ends with the caller lacks permission, or the API is not enabled for the project

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.

a service account has no My Drive; use user OAuth or domain-wide delegation with subject to create documents

create_document ran on a server that uses a service account with no Subject. Set Subject, or use user OAuth. See Choose how the server authenticates.

service account token exchange failed (status <code>: unauthorized_client); domain-wide delegation is not authorized for this service account and scope in the Workspace Admin console

The server has a Subject, but the service account’s client ID isn’t authorized for the scope the server requests. Authorize documents.readonly, or documents when Allow Writes is on. See Authorize domain-wide delegation.

service account token exchange failed (status <code>: <error>), with an error other than unauthorized_client

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.

expected a Google Docs document, not another Google file type

The document argument is the URL of a Sheets, Slides, or Forms file. Pass a Google Docs document.

document revision changed; read the document again before editing

The document changed after the read that returned revision_id. Run get_document again and retry with the new revision_id.

editing documents with pending suggestions is not supported; accept or reject them in Google Docs first

The document has pending suggestions. Accept or reject them in Google Docs, then retry.

edit <n>: text is not unique (<count> matches); set all_occurrences or use a longer match

The text in find occurs more than once. Use a longer piece of text, or set all_occurrences.

edit <n>: insertion anchor must occur exactly once (<count> matches)

The text in after or before is missing from the tab or occurs more than once. Use a longer piece of text that occurs once.

edit <n>: text was not found in a contiguous editable text region

The text in find isn’t in the tab as plain text, or it spans table cells. Run get_document with FORMAT_TEXT and copy the text from the result.

An error that ends with rate limited, retry later

The Google Docs API quota for the project or the user is exhausted. Wait, then retry.

connection_required

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.

scope_upgrade_required

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.

unable to resolve "type.googleapis.com/redpanda.mcps.google_docs.v1.GoogleDocsMCPConfig": "not found"

Your rpk ai version is older than 0.2.112 and doesn’t recognize this server’s configuration type. Run rpk ai upgrade, then retry.