> For the complete documentation index, see [llms.txt](https://docs.natoma.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.natoma.ai/apps/bigquery-remote.md).

# BigQuery (Remote)

{% hint style="warning" %}
**Early Access** — Reach out to your Natoma representative for access.
{% endhint %}

**Type:** Official

**Source Type:** Remote URL

**Source:** <https://bigquery.googleapis.com/mcp>

**Description:** BigQuery (Remote) MCP server provides AI assistants with access to Google BigQuery via Google's official remote MCP endpoint. Google hosts the MCP infrastructure at a globally available HTTPS endpoint; access is controlled through Google Cloud IAM, and every tool invocation is logged through Cloud Audit Logs.

***

## Prerequisites

* The **BigQuery API** enabled on the project (`bigquery.googleapis.com`).
* The **`gcloud` CLI** with the `beta` component, or access to Cloud Shell.
* An identity (user or service account) authenticated via `gcloud auth application-default login`.
* The IAM roles listed under **Required IAM Permissions** below.

## Required IAM Permissions

Minimum roles to enable and use the MCP server:

| Role                                   | Purpose                                           |
| -------------------------------------- | ------------------------------------------------- |
| `roles/serviceusage.serviceUsageAdmin` | Required to run `gcloud beta services mcp enable` |
| `roles/mcp.toolUser`                   | Required to invoke MCP tools                      |
| `roles/bigquery.jobUser`               | Required to run BigQuery query jobs               |
| `roles/bigquery.dataViewer`            | Required to read table data                       |

Additional roles for write operations:

| Role                        | Purpose                               |
| --------------------------- | ------------------------------------- |
| `roles/bigquery.dataEditor` | Read and write table data             |
| `roles/bigquery.dataOwner`  | Full control over datasets and tables |

{% hint style="info" %}
**Cross-project setups:** if your AI client authenticates in one project but queries data in another, enable the MCP server on **both** projects, and ensure the authenticating identity has the appropriate roles in the data project.
{% endhint %}

***

## Setup

### Admin Setup (one-time)

#### Step 1: Enable the BigQuery API

In the [Google Cloud Console](https://console.cloud.google.com/), confirm your project is selected, then navigate to **APIs & Services > Library**, search for **BigQuery API**, and click **Enable**. (If it's already enabled, the button reads **Manage** — proceed to Step 2.)

Or, from the CLI:

```shell
gcloud services enable bigquery.googleapis.com \
    --project=YOUR_PROJECT_ID
```

#### Step 2: Enable the BigQuery Remote MCP Server

The MCP enable command is a `gcloud beta` feature and does not yet have a dedicated UI in the Cloud Console. The easiest no-install option is **Cloud Shell**, which runs in your browser.

1. In the Google Cloud Console, click the **Activate Cloud Shell** button in the top-right toolbar (the `>_` icon).
2. Run:

```shell
gcloud beta services mcp enable bigquery.googleapis.com \
    --project=YOUR_PROJECT_ID
```

3. If prompted to install the `beta` component, confirm with `Y`.

The same command works from a local `gcloud` install.

#### Step 3: Create a Web Application OAuth Client

Natoma is a web-based platform — you need a **Web application** OAuth client (not a Desktop client).

1. In the Google Cloud Console, go to **APIs & Services > Credentials** (or **Google Auth Platform > Clients**).
2. Click **Create Credentials > OAuth client ID**.
3. Set the **Application type** to **Web application**.
4. Give it a descriptive name, e.g. `Natoma BigQuery MCP`.
5. Under **Authorized redirect URIs**, add Natoma's OAuth callback URL:

{% hint style="warning" %}
Use exactly this redirect URI — Google will reject the OAuth flow if it doesn't match.
{% endhint %}

```
https://api.natoma.app/mcp/server/callback
```

6. Click **Create**. Copy the **Client ID** and **Client Secret** immediately — the secret is only shown once. Store them in a secure location.

In Natoma, an admin adds **BigQuery (Remote)** under **Apps** and enters the **Client ID** and **Client Secret**.

### Authorize Your Connection

When prompted while creating the connection in Natoma, click **Authorize** and sign in with the Google account that holds the required BigQuery IAM roles.

***

## Available MCP Tools

| Tool               | Description                             | Read-only |
| ------------------ | --------------------------------------- | --------- |
| `list_dataset_ids` | Lists all datasets in a project         | Yes       |
| `list_table_ids`   | Lists all tables in a dataset           | Yes       |
| `get_dataset_info` | Returns metadata about a dataset        | Yes       |
| `get_table_info`   | Returns schema and metadata for a table | Yes       |
| `execute_sql`      | Runs a SQL query and returns results    | No        |

Read-only tools carry the `mcp.tool.isReadOnly = true` attribute, so you can restrict agents to non-mutating operations via organization policy.

## Limitations

* `execute_sql` does **not** support querying Google Drive external tables.
* Queries have a default timeout of **3 minutes**. Longer queries are canceled.
* The MCP server does not add quotas, but standard **BigQuery API quotas** (e.g. `jobs.Query` rate limits) still apply.

## Troubleshooting

* **"Permission denied" when enabling the MCP server** — ensure the account has `roles/serviceusage.serviceUsageAdmin` on the project.
* **"Forbidden" errors when invoking tools** — confirm that `roles/mcp.toolUser`, `roles/bigquery.jobUser`, and `roles/bigquery.dataViewer` are all granted to the authenticating identity.
* **OAuth flow not completing** — verify the OAuth client's redirect URI matches `https://api.natoma.app/mcp/server/callback` exactly, and that `gcloud auth application-default login` completed successfully.
* **MCP server enabled in the wrong project** — for cross-project setups, re-run the enable command targeting the project where BigQuery resources live.