Google BigQuery Managed MCP Server
Connect agents to BigQuery so they can browse datasets and answer questions with GoogleSQL. Every result row comes back as a record keyed by column name, so a data policy can mask or filter one column, and a byte limit refuses any query that would scan too much data.
After reading this page, you will be able to:
-
Set up Google Cloud access for the BigQuery server with per-user OAuth or a service account
-
Create the Google BigQuery managed MCP server with a byte limit on every query
-
Run a query from the Inspector and mask or filter its columns with a data policy
|
The Google BigQuery managed MCP server is in Preview. If you don’t see Google BigQuery in the marketplace picker, contact Redpanda support. |
What this MCP server does
The Google BigQuery managed type calls Google’s hosted BigQuery MCP server. Google enables that server when you enable the BigQuery API. The managed type exposes these tools:
| Tool | What it does |
|---|---|
|
List the datasets in a project. The |
|
List the tables and views in a dataset. The |
|
Return a table’s schema (column names, types, modes, descriptions, and nested fields), size, timestamps, partitioning, and clustering. The result never includes rows. The |
|
Run a read-only |
|
Run a data manipulation language (DML) or data definition language (DDL) statement, such as |
The query tool is the only one that returns table data. Later pages also come from query, so a data policy on query covers every read. Google’s get_dataset_info tool isn’t exposed, because a dataset’s access list holds user email addresses.
Before it runs any statement, the server asks BigQuery for a dry run, which checks the SQL and estimates the bytes it would process. The dry run adds one call to BigQuery before every statement, and its result decides what happens next:
-
A statement whose estimate is above
Max Bytes Processedis refused before it runs. -
Errors from the dry run, such as a syntax error or an unknown column, describe the SQL rather than the data, so they reach the agent, which can fix its query.
-
Errors raised while a statement runs are withheld, because BigQuery can quote cell values in them. For example, a failed
CAST(email AS INT64)names the email address that failed to convert.
How rows become records
BigQuery returns each row as a positional list of strings. The server decodes every row against the result’s schema into a record keyed by column name:
| BigQuery type | Value in a record |
|---|---|
|
Number, or a string for values beyond 253 so they stay exact |
|
Number, with |
|
Boolean |
|
RFC 3339 string, for example |
|
String |
|
The JSON text, as a string. Its keys are data, not schema, so a data policy masks or drops the whole value. |
|
Object. A |
|
Array |
Every record carries every column, with NULL as null. A column name that a data policy can’t address, such as `Annual Income` with a space, is refused before the query runs, with a suggestion to alias it, for example SELECT `Annual Income` AS annual_income.
Prerequisites
-
A Google Cloud project with the BigQuery API enabled. New projects have it enabled already. The project runs and pays for every query the server sends.
-
Billing enabled on the project if agents will run
execute_sql. The BigQuery sandbox doesn’t support DML. See BigQuery sandbox. -
The
gcloudCLI, signed in as a user who can grant Identity and Access Management (IAM) roles on 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.
Choose how the server authenticates
The server supports two authentication modes:
| Mode | Who BigQuery sees | Use it for |
|---|---|---|
User OAuth (recommended) |
Each calling user, with their own Google token from the token vault |
Agents that act for a person. BigQuery’s own IAM, column-level access control, row-level security, and data masking all apply per user. |
Service account |
One shared Google service account for every caller |
Agents with no person behind them, such as agents run by a trigger. BigQuery can’t tell callers apart, so data policies matter more. |
Grant BigQuery roles
Whichever mode you choose, grant these IAM roles to each user (for user OAuth) or to the service account. Grant each role on the project or dataset shown in the table. MCP Tool User and BigQuery Job User go on the server’s project even when the data is in another project.
| Role | Grant it on | Purpose |
|---|---|---|
MCP Tool User ( |
The server’s |
Calling Google’s MCP tools |
BigQuery Job User ( |
The server’s |
Running queries |
BigQuery Data Viewer ( |
Each project that holds tables agents read, or individual datasets in it |
Reading table data |
BigQuery Data Editor ( |
Each project or dataset that |
Changing data and creating or dropping tables with |
Google checks MCP Tool User on the project that a tool call names, not on the project that owns the data. Every query and execute_sql call names the server’s Project ID. A query can therefore read a table in another project where the identity holds only BigQuery Data Viewer. The list_datasets, list_tables, and get_table tools name the project in their project_id argument, so browsing another project also needs MCP Tool User on that project.
For example, to grant roles/bigquery.jobUser to one user, replace <project-id> with the server’s Project ID and <email> with the user’s email address:
gcloud projects add-iam-policy-binding <project-id> \
--member="user:<email>" \
--role="roles/bigquery.jobUser"
To grant roles to many users at once, use a Google group as the member instead, for example group:analysts@example.com.
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. |
-
In the Google Auth Platform for the project, 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
https://www.googleapis.com/auth/bigqueryscope.
-
-
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.
Store the client secret
Store the client secret in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE ID, for example GOOGLE_BIGQUERY_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-bigquery. -
Enter the
Client IDfrom the Google client, and setClient secret referenceto the secret, for exampleGOOGLE_BIGQUERY_CLIENT_SECRET. -
Under
Scopes, click Add scope and addhttps://www.googleapis.com/auth/bigquery. -
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.
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-bigquery --project=<project-id> -
Grant it the roles from Grant BigQuery roles, for example:
for role in roles/mcp.toolUser roles/bigquery.jobUser roles/bigquery.dataViewer; do gcloud projects add-iam-policy-binding <project-id> \ --member="serviceAccount:adp-bigquery@<project-id>.iam.gserviceaccount.com" \ --role="$role" doneIf agents read tables in other projects, also grant BigQuery Data Viewer there. If they browse other projects with
list_datasets,list_tables, orget_table, also grant MCP Tool User there. See Grant BigQuery roles. -
Create a JSON key for it:
gcloud iam service-accounts keys create adp-bigquery-key.json \ --iam-account=adp-bigquery@<project-id>.iam.gserviceaccount.com -
Store the whole key file in the Agentic Data Plane secret store under an
UPPER_SNAKE_CASEID, for exampleGOOGLE_BIGQUERY_SA_KEY, with the Multiline value format. See Create a secret. -
Delete the local key file once the secret is stored.
AI Gateway exchanges the key for short-lived access tokens and checks the key when the server starts. If the secret doesn’t hold a valid service account JSON key, the server’s tools can’t be listed and every call fails.
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 BigQuery card in the marketplace picker.
-
Replace the suggested
Name, and optionally add aDescription. -
Set
Project IDto the project that runs and pays for queries, for examplemy-analytics-project. -
Optional: When the tables agents read are in a project other than the
Project ID, add each of those projects underData Project Ids, for examplemy-data-project. You can add up to 20 projects. Leave the list empty when the data is in theProject ID. -
Optional: Set
Max Bytes Processed. Any statement whose dry run estimates more bytes processed is refused. Leave it empty for 10 GiB (10,737,418,240 bytes). -
Optional: Set
Max Rows, the most rows onequerycall or page returns, from 1 to 3,000. Leave it empty for 1,000. -
Optional: Turn on
Allow Writesto add theexecute_sqltool. Leave it off for a read-only server. -
Under
Auth, select one mode:-
User OAuth: SetProvider Nameto the provider you created, for examplegoogle-bigquery, and addhttps://www.googleapis.com/auth/bigqueryunderRequired Scopes. -
Service Account: SetKey Secret Refto the secret that holds the key, for exampleGOOGLE_BIGQUERY_SA_KEY.
-
-
Click Create server.
Every query and execute_sql statement runs in, and is billed to, the server’s Project ID. You can’t change the billing project with a tool argument. A query can still read tables in other projects when the identity holds the roles described in Grant BigQuery roles.
Point the server at the data
A data project is a Google Cloud project that holds the tables agents read. When the data is in a project other than the Project ID, list each such project under Data Project Ids. The list tells the agent where the data is. It doesn’t restrict access. A call can still name any project, and BigQuery IAM decides what each caller can read. The list changes two things:
-
list_datasets,list_tables, andget_tablebrowse the first data project when a call doesn’t setproject_id. With an empty list, they browse theProject ID. -
The browse tools'
project_idargument and the descriptions ofqueryandexecute_sqlname the data projects, so the agent knows where to look and how to write a table’s full name, for examplemy-data-project.crm.customers.
A dataset.table name without a project always resolves in the Project ID, because that project runs the query. The descriptions of query and execute_sql always say so, and tell the agent to write a table in any other project as project.dataset.table. The list adds the data project names to that note. When BigQuery can’t find a dataset that a query names in the Project ID, the error adds a hint with the same advice. With data projects set, the hint names them. With an empty list, it says to write the table with its project.
You can add or change the list on an existing server. Agents see the new tool descriptions when they reconnect.
To browse another project, pass its ID as project_id to list_datasets, list_tables, or get_table. As described in Grant BigQuery roles, these calls also need MCP Tool User on that project. If the identity lacks that role on that project, use query to read the project’s INFORMATION_SCHEMA views instead, for example:
{"sql": "SELECT table_schema, table_name FROM `<other-project-id>`.`region-<region>`.INFORMATION_SCHEMA.TABLES"}
Replace <other-project-id> with the project’s ID and <region> with the region that holds the project’s datasets, for example us or eu. A region-qualified view needs permissions on the whole project, such as BigQuery Data Viewer. If the identity can read only some of the project’s datasets, query each dataset’s view instead, for example `<other-project-id>`.<dataset>.INFORMATION_SCHEMA.TABLES, where <dataset> is the dataset’s ID.
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. 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 a read-only server with per-user OAuth and a 1 GiB byte limit, pass the configuration as JSON in --managed.config:
rpk ai mcp-server create google-bigquery \
--enabled \
--description "BigQuery with per-user OAuth" \
--managed.config '{
"@type": "type.googleapis.com/redpanda.mcps.google_bigquery.v1.GoogleBigQueryMCPConfig",
"projectId": "my-analytics-project",
"maxBytesProcessed": "1073741824",
"maxRows": 1000,
"allowWrites": false,
"userOauth": {
"providerName": "google-bigquery",
"requiredScopes": ["https://www.googleapis.com/auth/bigquery"]
}
}'
For a service account, replace the userOauth object with "serviceAccount": {"keySecretRef": "GOOGLE_BIGQUERY_SA_KEY"}.
When the data is in another project, add "dataProjectIds": ["my-data-project"] to the --managed.config JSON. This field needs rpk ai 0.2.111 or later. An older version rejects it with unknown field "dataProjectIds". Run rpk ai upgrade, then retry.
To add data projects to an existing server, update it in place from a manifest:
-
Export the server as a manifest:
rpk ai mcp-server get google-bigquery -o yaml > google-bigquery.yaml. -
Add
data_project_idsundermanaged.configin the manifest. -
Preview the change:
rpk ai mcp-server diff -f google-bigquery.yaml. -
Apply it:
rpk ai mcp-server apply -f google-bigquery.yaml. The server keeps its URL. -
Check the tool descriptions agents see:
rpk ai mcp-server tools list google-bigquery -o json.
An rpk ai version older than 0.2.111 rejects the manifest too.
Run a query
-
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
list_datasetswith no arguments. It lists the datasets in the server’s first data project, which is theProject IDwhenData Project Idsis empty. See Test an MCP Server’s Tools with the Inspector. -
Run
querywith a GoogleSQL statement:{"sql": "SELECT customer_id, income, region FROM `my-analytics-project.crm.customers` LIMIT 2"}
The result looks like this:
{
"columns": [
{"name": "customer_id", "type": "INTEGER", "mode": "NULLABLE"},
{"name": "income", "type": "FLOAT", "mode": "NULLABLE"},
{"name": "region", "type": "STRING", "mode": "NULLABLE"}
],
"records": [
{"customer_id": 288, "income": 86764.66, "region": "EMEA"},
{"customer_id": 301, "income": 41200, "region": "AMER"}
],
"total_bytes_processed": "48",
"next_page_token": "",
"truncated": false,
"running": false
}
The columns list reports the type names that BigQuery’s API uses, such as INTEGER for INT64, FLOAT for FLOAT64, and RECORD for STRUCT.
When next_page_token isn’t empty, call query again with the same sql, unchanged, and with page_token set to the token. Repeat until next_page_token comes back empty. The last page can have no rows. Each page call checks the SQL again, with its own dry run.
A call waits up to a minute for a query to finish, and less when the caller’s own time limit is shorter. If the query is still running, the result has running set to true, no records, and a next_page_token. Call query again with the same sql and that token to keep waiting. A call without the token starts a second query, which BigQuery also bills.
If truncated is true, the result holds more rows than one page returned, and no next_page_token is available to read the rest. Narrow the query, or raise max_rows up to the server’s Max Rows.
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-bigquery query \
--args '{"sql":"SELECT customer_id, income, region FROM `my-analytics-project.crm.customers` LIMIT 2"}'
Govern columns with data policies
Because every column has a name, a data policy on query can target one column. Add policies on the server’s Data Policies tab. See Shape Tool Data with Data Policies.
For example, this policy masks the income column and keeps only the EMEA rows in query results for one user:
rpk ai mcp-server update google-bigquery --data-policies '{
"displayName": "emea-rows-masked-income",
"tools": ["query"],
"principals": ["User:analyst@example.com"],
"shaping": {
"response": {
"fieldActions": {
"rules": [
{"selector": {"jsonPath": "$.records.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, query then returns only the rows whose region is EMEA, with income as [REDACTED]. To mask a field inside a STRUCT column, select it by path, for example $.records.account.region.
The agent writes the SQL, so it also chooses the column names that policies match on. Keep these points in mind:
-
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. With an absence-safe rule on
$.records.income, a query such asSELECT income AS xreturns the column unmasked under another name. A strict rule finds noincomefield in that result, so the call is denied. -
Create strict 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 create it with
--data-policiesas in the example. See Select fields. -
Allowlist mode limits names, not values. With Drop fields without policy and a Keep rule on
$.records.customer_id, a query such asSELECT income AS customer_idstill returns income under the kept name. Allowlist mode also drops the result’scolumns,next_page_token,total_bytes_processed,truncated, andrunningfields unless you keep them. Keep$.next_page_tokenand$.runningif agents need to page through results or wait for slow queries. -
Rely on BigQuery’s own controls to limit access. With user OAuth, every query runs as the calling user, so BigQuery IAM, column-level access control, row-level security, and data masking apply per user. Data policies shape what a permitted query returns.
-
Keep
Allow Writesoff unless you need it. A data policy onquerydoesn’t governexecute_sql. A statement such asCREATE TABLE … AS SELECTorEXPORT DATAcan copy a masked column into a new table or a Cloud Storage bucket.
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 the errors meant to help the agent fix its SQL, such as a syntax error, the alias suggestion, and the byte limit. To see the full error, run the query as a user no policy targets.
Troubleshooting
| Symptom | What to check |
|---|---|
|
The dry run estimated more bytes than |
|
The dry run found a problem with the SQL, such as a syntax error or an unknown table or column. The message comes from BigQuery. Fix the query and retry. |
|
The query names a dataset without its project, so BigQuery looks for it in the server’s |
|
A result column has a name with spaces or other characters a data policy can’t select. Alias it in the query, as the message suggests. |
|
The statement passed the dry run but failed while running, for example on a failed type conversion. Check the query against the table’s schema from |
|
Dynamic SQL, such as |
|
The query ran for five minutes, and BigQuery stopped it. See Limitations. Narrow it before you run it again, for example by filtering on partition or clustering columns or by selecting fewer columns. |
|
The query was still running when the call stopped waiting, and BigQuery returned no job, so there’s no |
|
The |
|
A call with |
|
The server checks the query again on every page, and it now fails, for example because the table grew past |
|
The identity lacks a role. Check the roles in Grant BigQuery roles for the user or the service account. |
|
The identity lacks a role the query needs, such as BigQuery Job User on the project or BigQuery Data Viewer on a table it reads. See Grant BigQuery roles. |
|
The identity lacks MCP Tool User on the project that the message names. Grant MCP Tool User on that project. If you only need to list that project’s datasets and tables, use |
|
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 and doesn’t report why it rejected the key. |
|
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 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 |
|
A data policy applies to the caller, so the tool’s error is withheld, or a strict rule matched nothing, for example after the query aliased a governed column. Run the query as a user no policy targets to see the error. |
|
Your |
|
Your |
Limitations
-
Google’s BigQuery MCP server returns at most 3,000 rows per call. It doesn’t support Google Drive external tables.
-
BigQuery stops any statement the server runs after five minutes.
-
The server checks
Max Bytes Processedagainst the dry run’s estimate before a statement runs. It doesn’t enforce the limit while the statement runs.