Google Sheets Managed MCP Server
Connect agents to Google Sheets so they can read and update spreadsheet rows with each user’s own Google permissions. Every row comes back keyed by its column header, so a data policy can mask, drop, or filter one column without hiding the rest of the sheet.
After reading this page, you will be able to:
-
Enable the Google Sheets API in a Google Cloud project and create the OAuth client the server needs
-
Configure an OAuth provider and create the Google Sheets managed MCP server
-
Mask or filter columns with a data policy
| The Google Sheets managed MCP server is in Preview. If you don’t see Google Sheets in the marketplace picker, contact Redpanda support. |
What this MCP server does
The Google Sheets managed type calls the Google Sheets API directly and authenticates per user through the token vault in AI Gateway. Every call runs with the calling user’s own Google token, so a user can reach only the spreadsheets they can open in Google Sheets. Per-user OAuth is the only authentication mode this type supports.
Each row comes back as a record whose keys come from the sheet’s column headers. See How rows become records.
The Google Sheets managed type exposes these tools:
| Tool | What it does |
|---|---|
|
Return a spreadsheet’s title, locale, time zone, and its grid sheets (tabs), with each sheet’s title, row count, column count, and frozen rows. The result never includes cell values. |
|
Return the rows below the header row of one sheet, as |
|
Overwrite cells in existing rows. Each record names its row with |
|
Add rows after the last row that holds data. Records are keyed by column key and can’t include |
Keep these behaviors in mind:
-
Blank rows are skipped.
read_rowsskips a row when every cell it returns is empty, including when you passcolumns. Use a record’s_rowto find its row, not its position inrecords. -
Pages can be empty. A page that falls in a run of blank rows can come back empty, so keep paging until
next_start_rowis0, which means the read reached the end of the sheet. -
Write values are typed. Values must be strings, numbers, booleans, or
null. A string is always stored as literal text and never evaluated as a formula, so a value such as=B2can’t copy another cell’s contents into the sheet. -
Some features aren’t available. Cell formatting, charts, formulas, filters, and sheet management aren’t supported.
With SQL exposure on, the server also presents each sheet as a read-only SQL table. See Expose sheets as SQL tables.
How rows become records
The server reads the column headers from one row of each sheet, set by Header Row in the server configuration (row 1 by default), and turns each header into a record key:
-
Letters A to Z become lowercase, and digits stay. Every run of other characters, including spaces, punctuation, and letters outside A to Z, becomes an underscore (
_). Leading and trailing underscores are removed. -
A key that starts with a digit gets a leading underscore.
-
A header with no letters A to Z or digits, such as
名前, becomesu_plus the hexadecimal encoding of its lowercased UTF-8 bytes. -
A column whose header is empty becomes
col_plus its column letter.
These headers produce these record keys:
| Header | Record key |
|---|---|
|
|
|
|
|
|
|
|
|
|
(empty, column D) |
|
Each record also carries _row, its 1-based row number in the sheet, and holds every column the read returns. An empty cell reads as "".
The header row defines the table. The server returns and writes only the columns within the header row’s width. It never returns or writes the header row or any row above it. If two headers produce the same key, such as Email and EMAIL, the read fails with an error that names both columns. Rename one of the headers.
Prerequisites
-
A Google Cloud project where you can enable APIs and create OAuth clients. The project runs no compute, because AI Gateway calls the Google Sheets 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.
-
Familiarity with user-delegated OAuth.
Enable the Google Sheets API
Enable the Google Sheets API on the Google Cloud project that will own the OAuth client. You create the client in Create the OAuth client. Replace <project-id> with your project ID:
gcloud services enable sheets.googleapis.com --project=<project-id>
Until you enable the API, tool calls fail with a SERVICE_DISABLED error.
Configure the OAuth consent screen
| This configuration refers to a third-party product. Specific UI elements may not be up to date. |
In the Google Auth Platform for the project where you enabled the API:
-
On the Branding page, give the app a name your users recognize on the consent screen, 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
https://www.googleapis.com/auth/spreadsheetsscope.
For the full procedure, see Google’s Configure the OAuth consent screen and choose scopes guide.
Create the OAuth client
| This configuration refers to a third-party product. Specific UI elements may not be up to date. |
-
In the Google Auth Platform, open Clients and create a client.
-
Set Application type 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. -
Create the client, then copy its Client ID and Client secret.
Store the client secret
Store the client secret in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE ID, for example GOOGLE_SHEETS_CLIENT_SECRET, with the Single line value format. See Create a secret. The OAuth provider references the secret by its ID, so the secret value never appears in the MCP server’s configuration.
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-sheets. 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_SHEETS_CLIENT_SECRET. -
Under
Scopes, click Add scope and addhttps://www.googleapis.com/auth/spreadsheets. -
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.
If your organization already has a Google OAuth provider whose Scopes include https://www.googleapis.com/auth/drive, you can use that provider instead of adding the Sheets scope. The Google Sheets API accepts the Drive scope for reads and writes, so users who have already granted it don’t have to consent again. In that case, set the server’s Required Scopes to the Drive scope. The Drive scope grants access to the user’s whole Drive, so use the Sheets scope for a new provider.
|
Create the server
Before you start, create the OAuth provider. See Configure the OAuth provider.
-
Open MCP servers in the sidebar.
-
Click Add MCP server.
-
Click the Google Sheets card in the marketplace picker.
-
Replace the suggested
Name, and optionally add aDescription. -
Optional: Set
Header Rowto the row that holds the column headers on every sheet, from 1 to 1,000. Leave it empty for row 1. -
Optional: Turn on
Allow Writesto add theupdate_rowsandappend_rowstools. Leave it off for a read-only server. -
Optional: Under
Allowed Spreadsheet Ids, add the IDs of the only spreadsheets this server may open, up to 100. Leave the list empty to allow any spreadsheet each user can open.A spreadsheet’s ID is the part of its URL after
/d/. -
Under
Auth, setProvider Nameto the provider you created, for examplegoogle-sheets. -
Under
Required Scopes, addhttps://www.googleapis.com/auth/spreadsheets. -
Click Create server.
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. Every required scope must also be in the OAuth provider’s Scopes.
Configure from the CLI
You need rpk ai 0.2.100 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 the same server with rpk ai, pass the configuration as JSON in --managed.config:
rpk ai mcp-server create google-sheets \
--enabled \
--description "Google Sheets with per-user OAuth" \
--managed.config '{
"@type": "type.googleapis.com/redpanda.mcps.google_sheets.v1.GoogleSheetsMCPConfig",
"headerRow": 1,
"allowWrites": false,
"allowedSpreadsheetIds": ["1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd"],
"userOauth": {
"providerName": "google-sheets",
"requiredScopes": ["https://www.googleapis.com/auth/spreadsheets"]
}
}'
Connect your Google account and test
Each user connects their own Google account before the tools work for them:
-
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_spreadsheetwith the ID of a spreadsheet you can open:{"spreadsheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd"}The result lists the spreadsheet’s sheets. See Test an MCP Server’s Tools with the Inspector.
-
Run
read_rowswith one of the sheet titles:{"spreadsheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd", "sheet": "Customers", "max_rows": 2}
For a sheet whose headers are Customer ID, Annual Income, and Region, the result looks like this:
{
"columns": [
{"key": "customer_id", "header": "Customer ID", "letter": "A"},
{"key": "annual_income", "header": "Annual Income", "letter": "B"},
{"key": "region", "header": "Region", "letter": "C"}
],
"records": [
{"_row": 2, "customer_id": "288", "annual_income": "86764.66", "region": "EMEA"},
{"_row": 3, "customer_id": "301", "annual_income": "41200", "region": "AMER"}
],
"next_start_row": 4
}
Reads return every value as a string, formatted as Google shows it in the sheet, such as "86764.66" or "1/2/2026". Writes accept strings, numbers, booleans, and null.
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-sheets read_rows \
--args '{"spreadsheet_id":"1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abcd","sheet":"Customers","max_rows":2}'
Govern columns with data policies
Because every column has a predictable key, a data policy on this server can target one column by name. Add policies on the server’s Data Policies tab. See Shape Tool Data with Data Policies.
For example, this policy masks the annual_income key (the Annual Income column) and keeps only the EMEA rows in read_rows results for one user:
rpk ai mcp-server update google-sheets --data-policies '{
"displayName": "emea-rows-masked-income",
"tools": ["read_rows"],
"principals": ["User:analyst@example.com"],
"shaping": {
"response": {
"fieldActions": {
"rules": [
{"selector": {"jsonPath": "$.records.annual_income"}, "mask": {"redact": {}}}
]
},
"rowFilters": [
{"path": "$.records", "expression": "@.region == \"EMEA\""}
]
}
}
}'
The --data-policies flag replaces the server’s whole list of data policies. Pass every policy the server should keep.
|
For analyst@example.com, read_rows then returns only the rows whose region is EMEA, with annual_income as [REDACTED]. Every other user still sees every row.
Keep these points in mind when you write policies for this server:
-
Keep mask and drop rules strict. A strict rule denies the call when a returned record is missing its field, and an absence-safe rule lets the result through instead. A policy follows the header, not the data. If someone renames
Annual Income, its key changes, and a strict rule on$.records.annual_incomedenies the call instead of returning the column under its new key. -
Write exact paths, and create rules in the YAML editor or the CLI. Rules you create in the form are absence-safe by default, so make the rule strict in the YAML editor, or set it with
--data-policiesas in the example. Rules passed that way are strict unless you mark them absence-safe. Use exact paths such as$.records.annual_income, not descendant selectors such as$..annual_income, which can’t be strict. See Select fields. -
Put row filters on
$.records. Compare a record key, such as@.region == "EMEA". -
Use allowlist mode to return only the columns you name. Turn on Drop fields without policy and add Keep rules. A column someone adds to the sheet later stays hidden too. Allowlist mode also drops
_rowand the result’scolumnsandnext_start_rowfields unless you keep them. Keep$.records._rowif agents need row numbers forupdate_rows, and$.next_start_rowif they need to page through the sheet. -
Govern writes with request rules. Add them to
update_rowsandappend_rows. A drop rule on$.records.annual_incomestops agents from writing that column. -
Pin the server to known spreadsheets. List them in
Allowed Spreadsheet Ids. A mask on one header doesn’t cover the same figures under a different header or on another sheet.
When a data policy applies to a caller and a tool, the agent never sees that tool’s own errors. Every tool error reaches the agent as [policy] response withheld: required data-access transforms could not be applied. That includes errors that explain the problem, such as an unknown sheet name or a refused write. To see the full error, call the tool as a user that no policy targets.
Expose sheets as SQL tables
The Google Sheets server can also present each sheet as a read-only SQL table, so an agent can read a sheet’s rows as table columns instead of raw records. SQL exposure is the Enabled toggle under Queryable in the server’s configuration. SQL exposure adds two tools:
-
list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed. -
execute_query: Run one query against a table and return a page of rows plus a cursor for the next page. These tables accept no filters, so anexecute_querycall that passes a predicate fails.
What the tables hold
The server reads the catalog from Google rather than storing it with its configuration, and reuses each reading for a minute, so a header edit can take a minute or longer to reach the catalog. Each grid sheet of each spreadsheet in Allowed Spreadsheet Ids becomes one table:
-
The table name joins the spreadsheet title and the sheet title with
__. The server normalizes both titles the way it normalizes record keys and cuts each to 30 bytes, so the whole name fits a bare SQL identifier. -
The first column,
_row, holds the sheet’s 1-based row number as an integer. Every other column comes from the header row, in sheet order, and holds text. An empty cell reads as null. -
Each of those columns takes its name from the record key of its header. A key that is a SQL keyword gets a trailing underscore, and a key too long for an identifier is shortened and given a suffix that keeps it unique. See How rows become records.
-
A query returns at most 1,000 rows per page.
The server leaves a sheet out of the catalog when any of these applies, and the SQL exposure tab shows the reason:
-
The sheet isn’t a grid sheet, such as an object sheet that holds a chart or image, or a data source sheet.
-
The server can’t read the spreadsheet or the sheet’s header row.
-
The header row is empty or gives two columns the same key.
-
Two of the sheet’s columns resolve to the same SQL column name.
-
The sheet’s table name collides with another sheet’s.
-
The sheet falls past the first 30 grid sheets the server discovers.
To bring back a sheet skipped for a column collision, rename one of its headers. To bring back one skipped for a table collision, rename the sheet.
SQL exposure needs at least one spreadsheet in Allowed Spreadsheet Ids and allows at most 20. The list itself takes up to 100 for the other tools, so split a larger set across several servers.
Who reads the schema
Reading a sheet’s headers takes a Google connection, and the catalog belongs to the server rather than to one caller, so a single person’s connection discovers it. That person is the server’s schema owner.
Agentic Data Plane sets the owner for you. Whoever turns SQL exposure on becomes the owner. So does whoever changes what discovery reads, which is the spreadsheet list (including its order), the header row, or the server’s OAuth settings. Only a signed-in person can turn SQL exposure on or make those changes while it’s on, because the owner’s own Google connection discovers the schema. A service account can’t.
The Schema owner card on the server’s SQL exposure tab names the current owner, or reads Not set. Click Use my connection to take over as owner, which rediscovers the catalog with your connection. Save or discard the tab’s pending changes first, because the button stays disabled until you do. Turning SQL exposure off clears the owner.
| The server uses the owner’s connection only to read spreadsheet metadata and header rows. Rows always come back through the calling user’s own Google connection, so a caller still reads only the spreadsheets they can open in Google Sheets. The catalog is shared, though. Every caller of the server sees the spreadsheet titles, sheet titles, and headers the owner can read, as table names, table descriptions, and column names, even for a spreadsheet the caller can’t open. |
If the owner’s connection stops working, the server’s list_tables and execute_query tools fail until the owner reconnects or someone else takes over. When the owner opens the SQL exposure tab, the Schema owner card offers Manage connections so they can reconnect. Anyone else can click Use my connection to take over.
Other failures have different causes and fixes:
-
The owner can open none of the allowed spreadsheets. The connection works, so this is a sharing problem. The SQL exposure tab reports it. Share the spreadsheets with the owner’s Google account, or change the spreadsheet list.
-
Google refuses the owner’s connection for every spreadsheet. The Google Sheets API isn’t enabled on the project that owns the OAuth client, or the connection lacks the scope. The tab reports the reason. Fix the project or the scopes, not the sharing.
-
Google rate-limits discovery or is unavailable.
list_tablesandexecute_queryreport that the Google Sheets API was temporarily unavailable. The tables stay in the catalog, and the next attempt reads them again. -
A sheet’s header row changes while a query pages through it. The query fails and tells the caller to call
list_tablesagain.
To trim the catalog table by table, hide columns, retype a column, or serve a table under another name, use the SQL exposure tab on the server’s page. That tab works the same way for every managed type that offers SQL tables. See Narrow what the SQL tools expose. If the server’s page has no SQL exposure tab, SQL tools aren’t available in your organization. Without SQL tools, the create form doesn’t show Queryable either, so you can’t turn SQL exposure on, see the schema owner, or see why the server skipped a sheet.
Troubleshooting
| Symptom | What to check |
|---|---|
An error that contains |
The Google Sheets API isn’t enabled on the project that owns the OAuth client. See Enable the Google Sheets API. |
An error that contains |
The user’s Google connection doesn’t grant a scope the call needs. Add |
An error that ends with |
The Google Sheets API quota for the project or the user is exhausted. Google refills the quota every minute, so wait a minute and retry. With SQL exposure on, |
|
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. If the scope is missing from the OAuth provider’s |
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. |
|
Add the ID to |
|
The |
|
|
|
Two headers produce the same record key. Rename one of them. See How rows become records. |
|
|
|
A data policy applies to the caller, so the tool’s error is withheld, or a strict rule matched nothing, for example after a header was renamed. Call the tool as a user that no policy targets to see the error, and check the policy’s selectors against the current headers. |
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, such as |
|
Your |