Connect BigQuery to Claude: Control Tables and ML Models

If you need to connect BigQuery to Claude to automate data analysis, provision warehouse tables, or inspect machine learning models, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function calling logic and Google Cloud's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on /connect-bigquery-to-chatgpt-run-queries-and-manage-datasets/ or explore our broader architectural overview on /connect-bigquery-to-ai-agents-automate-jobs-and-row-access/.

Giving a Large Language Model (LLM) read and write access to an enterprise data warehouse like BigQuery is an engineering challenge. You have to handle Google Cloud OAuth 2.0 or Service Account token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with BigQuery's strict asynchronous job mechanics. Every time Google updates an endpoint or shifts IAM permission requirements, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for BigQuery, connect it natively to Claude Desktop, and execute complex data engineering workflows using natural language.

The Engineering Reality of the BigQuery API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Google Cloud APIs is painful. You are not just integrating a standard REST API - you are interfacing with a massively parallel data warehouse that operates on distinct architectural paradigms.

If you decide to build a custom BigQuery MCP server, here are the specific integration challenges you will face:

Asynchronous Query Jobs and Polling In standard CRUD APIs, a GET request returns data immediately. In BigQuery, executing a complex SQL query means creating an asynchronous job. The API endpoint (queries.create) might return a job reference rather than the final dataset if the execution takes longer than the specified timeout. An LLM has no inherent concept of asynchronous polling. You must build a translation layer that handles job ID extraction, triggers the correct queries.get polling loop, and formats the final pagination cursor back to the model in a predictable schema.

Granular IAM and Row-Level Access Policies BigQuery does not rely on simple read/write scopes. It uses a deeply hierarchical IAM model spanning Projects, Datasets, Tables, and Row-Level Access Policies. If an LLM attempts to run a query without the bigquery.tables.getData permission, or attempts to manipulate a dataset without bigquery.datasets.update, it will crash with a cryptic 403 error. Your MCP server must expose strictly defined tools that help the LLM navigate these permission boundaries, mapping natural language intents to the exact IAM policy endpoints.

Schema Complexity and Streaming Inserts Writing data to BigQuery dynamically is notoriously difficult. You can load jobs from Cloud Storage, or you can use the streaming insert API (tabledata.insertAll). When an LLM attempts to write rows, the payload must perfectly match the destination table's schema, including nested repeated records (arrays of objects). Furthermore, BigQuery enforces strict data type validations. A managed MCP server exposes tools like bigquery_table_rows_bulk_create with strictly defined JSON Schemas that guide the LLM to format payloads correctly, drastically reducing hallucinated fields or schema mismatches.

Handling Rate Limits at Scale BigQuery enforces quota limits on concurrent API requests, query execution times, and streaming inserts. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Google Cloud API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your client application - or the LLM framework calling the MCP server - is strictly responsible for implementing retry logic and exponential backoff.

How to Generate a BigQuery MCP Server with Truto

Truto's architecture derives MCP tools dynamically from the underlying integration's resource definitions. When you connect a Google Cloud Service Account to Truto, you can generate an MCP server that exposes BigQuery operations instantly.

There are two ways to generate this server.

Method 1: Via the Truto UI

This is the fastest path for internal tooling and administrative setup.

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected BigQuery account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can limit the server to specific HTTP methods (e.g., read-only) or specific resource tags.
6. Click Generate and copy the resulting MCP Server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the API

For B2B SaaS applications programmatically provisioning AI agents for end-users, you can generate MCP servers dynamically via the Truto API.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST https://api.truto.one/api/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BigQuery Data Analyst Server",
    "config": {
      "methods": ["read", "custom"],
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will return the secure URL:

{
  "id": "mcp_srv_987654321",
  "name": "BigQuery Data Analyst Server",
  "config": {
    "methods": ["read", "custom"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude is a matter of configuration. Because Truto MCP servers use the standardized Server-Sent Events (SSE) transport over JSON-RPC 2.0, no heavy SDK installation is required.

Method A: Via the Claude Desktop UI

If you are using the consumer-facing Claude Desktop app (or ChatGPT's custom connector settings), you can add the server directly through the interface.

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations -> Add MCP Server.
3. Paste your Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add.

Claude will immediately initiate a handshake, parse the available BigQuery tools, and make them available in your chat context.

Method B: Via the Manual Configuration File

For automated deployments or CLI configurations, you can edit the claude_desktop_config.json file. Truto supports the @modelcontextprotocol/server-sse proxy, allowing local clients to connect to remote SSE endpoints.

{
  "mcpServers": {
    "bigquery-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

If you generated the server with "require_api_token_auth": true, you must inject your Truto API key into the headers:

{
  "mcpServers": {
    "bigquery-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ],
      "env": {
        "SSE_HEADER_AUTHORIZATION": "Bearer YOUR_TRUTO_API_KEY"
      }
    }
  }
}

Hero Tools for BigQuery Automation

Truto dynamically generates a massive suite of tools covering the entire BigQuery API. Here are the highest-leverage tools available for AI agent workflows.

create_a_big_query_query

Executes a synchronous SQL query against BigQuery. This is the primary engine for data retrieval and DDL operations. If the query exceeds the timeout limit, it returns a job reference that must be polled. Requires bigquery.jobs.create on the project.

"Run a SQL query against the production_events dataset to find the top 10 most active users from yesterday. If the job returns incomplete, let me know the job ID."

get_single_big_query_query_result_by_id

Retrieves the paginated results of an asynchronous query job. When an agent runs a massive aggregation that times out, it uses this tool to fetch the final rows. Requires bigquery.jobs.get and bigquery.tables.getData.

"Check the status of job ID bquxjob_7654321. If it is complete, fetch the first 100 rows of the result set."

big_query_table_rows_bulk_create

Streams data directly into a BigQuery table without needing to spin up a load job. Excellent for logging agent actions, storing extracted telemetry, or capturing real-time events. Requires bigquery.tables.updateData.

"Stream the analyzed sentiment scores into the ml_results.sentiment_logs table. Here is the JSON payload containing the user ID, timestamp, and score."

list_all_big_query_models

Lists all BigQuery ML models deployed in a specific dataset. Vital for AI workflows that need to inspect available predictive models before invoking ML.PREDICT in a SQL query.

"List all the machine learning models available in the customer_churn_project dataset. Show me their model types and creation dates."

create_a_big_query_row_access_policy

Creates a granular row-level access policy on a specific table. This is critical for data governance, allowing an agent to automatically secure PII based on user attributes.

"Create a row-level access policy on the eu_customers table. The policy should restrict access so that only users with the region = EU attribute can read the rows."

create_a_big_query_dataset

Provisions a completely new, empty dataset within a project. Useful for agents tasked with setting up environments for new clients or analytical projects.

"Create a new dataset called q4_marketing_analytics in the current project. Set the default table expiration to 60 days."

To view the complete inventory of BigQuery tools, schemas, and required parameters, visit the BigQuery integration page.

Workflows in Action

Connecting an LLM to BigQuery unlocks autonomous data engineering. Here are two concrete workflows showing exactly how Claude uses these tools.

Workflow 1: Ad-Hoc Data Analysis and Insights

Persona: Data Engineer / Analytics Manager

A product team needs rapid insights on user churn, but writing the SQL, running the job, and formatting the output takes too long. They ask Claude to handle it.

"Analyze the churn_events table in the telemetry dataset. Write and run a SQL query to find the top 5 reasons users churned last week, then summarize the results."

Step-by-step execution:

1. Claude formulates the SQL statement using Standard SQL syntax.
2. Claude calls create_a_big_query_query passing the SQL string in the request body.
3. The BigQuery API executes the query. If it completes quickly, it returns the rows immediately.
4. Claude interprets the JSON row data, synthesizes the findings, and presents a natural language summary to the user.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant BQ as Google BigQuery

    User->>Claude: "Analyze churn_events table..."
    Claude->>MCP: Call create_a_big_query_query(query: "SELECT reason, COUNT(*) ...")
    MCP->>BQ: POST /projects/{projectId}/queries
    BQ-->>MCP: Returns query results (JSON)
    MCP-->>Claude: JSON-RPC Result
    Claude-->>User: Provides summary of churn reasons

Workflow 2: Automated Table Provisioning and Security Setup

Persona: Cloud Architect / DevOps Admin

An architect needs to spin up a secure environment for a new ML training pipeline. The tables need to be created and immediately secured with row-level policies.

"Create a new dataset called ml_training_data. Inside it, run a query to create a table called raw_inputs. Then, apply a row access policy to raw_inputs so only the service account ml-worker@my-project.iam.gserviceaccount.com can read it."

Step-by-step execution:

1. Claude calls create_a_big_query_dataset passing datasetReference.datasetId = "ml_training_data".
2. Claude calls create_a_big_query_query with a DDL statement (CREATE TABLE raw_inputs (...)) to provision the table structure.
3. Claude calls create_a_big_query_row_access_policy targeting the new table, supplying the specific IAM policy string to restrict access to the ml-worker service account.
4. Claude confirms to the user that the secure environment is ready.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant BQ as Google BigQuery

    User->>Claude: "Create ml_training_data dataset and secure it..."
    Claude->>MCP: Call create_a_big_query_dataset()
    MCP->>BQ: POST /projects/{projectId}/datasets
    BQ-->>MCP: Dataset created
    Claude->>MCP: Call create_a_big_query_query(DDL)
    MCP->>BQ: POST /projects/{projectId}/queries
    BQ-->>MCP: Table created
    Claude->>MCP: Call create_a_big_query_row_access_policy()
    MCP->>BQ: POST /projects/.../rowAccessPolicies
    BQ-->>MCP: Policy applied
    MCP-->>Claude: Success
    Claude-->>User: Environment provisioned and secured

Security and Access Control

Exposing an enterprise data warehouse to an LLM requires strict boundary control. Truto's MCP servers provide several mechanisms to lock down AI agent access:

• Method Filtering: Configure config.methods during server creation to restrict the LLM. Passing ["read"] ensures the server only exposes list and get operations, physically preventing the LLM from executing destructive DELETE or DROP commands.
• Tag Filtering: Group specific BigQuery resources (like models vs. datasets) using tags. An MCP server can be restricted to only expose tools tagged with ["ml_models"].
• API Token Authentication: By default, possessing the MCP URL grants access. By setting require_api_token_auth: true, you force the client to pass a valid Truto API token in the headers, adding a secondary identity check.
• Time-To-Live (TTL): Set an expires_at timestamp. Truto will automatically destroy the MCP server and clean up the underlying routing infrastructure when the timestamp is reached, ensuring temporary access doesn't turn into a permanent vulnerability.

Strategic Wrap-up

Connecting Claude to BigQuery transforms a passive LLM into an active data engineer. By leveraging the Model Context Protocol through Truto, you sidestep the massive technical debt of manually mapping Google Cloud's asynchronous job structures, complex JSON schemas, and IAM hierarchies.

Whether you are building autonomous analytics agents, automating data governance, or orchestrating BigQuery ML pipelines, managed MCP infrastructure allows your engineering team to focus on AI workflows rather than API maintenance.