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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.natoma.ai/apps/bigquery-remote.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.