Connect BigQuery
Connecting BigQuery moves the agents from sample data to your real project: catalog and lineage answers from your actual datasets, quality scoring and anomaly detection on your tables, job and cost analysis, and NL-to-SQL insights. With a separate write-scoped credential, governed dataset and access changes too. Until verified, BigQuery stays in 🟡 Evaluation.
Prerequisites
Section titled “Prerequisites”- Data Workers installed and registered with your coding agent (install guide)
- Permission to create a service account and grant IAM roles in your GCP project
- The project ID that holds the datasets you want visible
Step 1 — Create a least-privilege credential
Section titled “Step 1 — Create a least-privilege credential”Read agents can never mutate your systems, so a read-only service account is enough to start. Create a dedicated service account and grant it only:
roles/bigquery.metadataVieweron the projectroles/bigquery.dataVieweron the datasets in scope (dataset-level, not project-wide, where you can)- Optional, for job and cost analysis:
roles/bigquery.resourceViewer
Download a JSON key for the service account and store it where the agents run. Start with one dataset, verify, then widen scope — and never widen this credential to add write; write uses a separate credential (least-privilege guidance).
Checkpoint: a service-account JSON key exists whose IAM bindings are the three roles above at most.
Step 2 — Set the environment variables
Section titled “Step 2 — Set the environment variables”Set these in the shell your coding agent launches from, then restart the coding agent so the MCP server picks them up. The key file stays on your machine; nothing is sent to Data Workers.
export GOOGLE_APPLICATION_CREDENTIALS="</path/to/service-account.json>"export BIGQUERY_PROJECT_ID="<project-id>"Checkpoint: the variables are visible in the environment your coding agent starts from.
Step 3 — Verify
Section titled “Step 3 — Verify”Setting a credential is not the same as a working connection. Ask:
Test the connection to my BigQuery catalog.
The agent makes a real call to your project. BigQuery shows 🟢 Connected only after that live test passes; a failure reports 🔴 with the reason. Full model: Verify your setup.
Checkpoint: BigQuery reports 🟢 Connected.
Supported operations
Section titled “Supported operations”| Operation | Status |
|---|---|
| Discovery (datasets, tables, assets) | Supported |
| Catalog writes (create/update/drop objects) | Supported — write-scoped credential required |
| RBAC (role-based access enforcement) | Supported |
| Policy attachment and enforcement | Supported |
| Credential vending (scoped, time-bound tokens) | Not supported — use GCP Application Default Credentials or Workload Identity Federation instead |
Unsupported operations return a clear error naming the connectors that do support them — never a pretend success.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Still answering from sample data | Variables set in a different shell, or agent not restarted | Set them in the shell your coding agent launches from, restart it |
| 🔴 with a permission error | Service account missing a viewer role on the dataset | Re-check the Step 1 IAM bindings on that dataset |
| 🔴 with “could not load credentials” | Key path wrong, or file unreadable by the agent process | Point GOOGLE_APPLICATION_CREDENTIALS at the absolute path of the JSON key |
| Job/cost questions come back empty | No roles/bigquery.resourceViewer | Add the optional role from Step 1 |