Activate BigQuery for an Agent

Use BigQuery when an analyst agent needs to inspect datasets, run SQL, build reports, or answer business questions from your Google Cloud data warehouse.

TeamDay can expose BigQuery in two ways:

• BigQuery MCP gives the agent structured BigQuery tools.
• gcloud and bq CLI let the agent run direct Google Cloud and BigQuery commands when a task needs the native CLI.

For scheduled reports and shared analyst agents, use a Google Cloud service account. For one-off interactive work owned by a human, gcloud user login is also supported.

What gets enabled

After setup, the selected agent can use:

• a BigQuery MCP server attached to the agent
• the gcloud and bq commands inside the runner
• credentials stored in TeamDay secrets or in the agent runner's Google Cloud config
• a writable private temp directory for command-line tools that need temporary files

BigQuery access still comes from Google Cloud IAM. TeamDay does not grant data access by itself; it only gives the agent a configured way to use the credentials you provide.

Before you start

You need:

• owner access in your TeamDay organization
• a Google Cloud project with the BigQuery API enabled
• datasets or authorized views the agent is allowed to read
• a TeamDay agent, usually Analyst or Data Analyst

Grant the Google identity at least:

• roles/bigquery.jobUser on the billing/query project
• roles/bigquery.dataViewer on the datasets the agent should read

Use narrower dataset permissions, authorized views, or custom roles when the agent should only see part of the warehouse.

Option A: Service account

Use this for scheduled missions, production reports, and shared agents.

1. In Google Cloud, create a service account for the TeamDay analyst.
2. Grant it BigQuery permissions on the project and datasets it should access.
3. Create a JSON key for the service account.
4. In TeamDay, open Settings -> MCP servers.
5. In Optional MCP helpers, find BigQuery.
6. Enter the Google Cloud project ID.
7. Set the BigQuery location, for example US or EU.
8. Paste the full service account JSON.
9. Click Enable BigQuery MCP.
10. Open the saved BigQuery server and attach it to the analyst agent from Agent access.
11. Start a new chat or restart any existing runner session so the agent loads the new MCP server.

The service account JSON is saved as a TeamDay secret and referenced by the MCP server configuration. The agent sees the configured BigQuery tools, not the raw secret value.

Option B: gcloud user login

Use this when a human owner wants the analyst to operate with their Google Cloud identity.

1. In TeamDay, open Settings -> MCP servers.
2. In Optional MCP helpers, find BigQuery.
3. Enter the Google Cloud project ID and BigQuery location.
4. Leave the service account JSON field empty.
5. Click Enable BigQuery MCP.
6. Attach the BigQuery MCP server to the analyst agent from Agent access.
7. Open a runner shell for that agent or ask the agent to authenticate with:

gcloud auth application-default login --no-launch-browser
gcloud config set project YOUR_PROJECT_ID
bq query --use_legacy_sql=false 'select 1 as ok'

Follow the login URL and paste the verification code back into the runner shell when Google asks for it.

The login must happen in the TeamDay runner environment, not only on your laptop, because the agent needs credentials available where it runs.

CLI setup

Owners can also configure BigQuery from the TeamDay CLI:

teamday mcp setup bigquery --project=YOUR_PROJECT_ID --location=US --agent="Analyst"

With a service account:

teamday mcp setup bigquery \
  --project=YOUR_PROJECT_ID \
  --location=US \
  --service-account-json="$(cat service-account.json)" \
  --agent="Analyst"

The CLI creates or updates the BigQuery MCP server and attaches it to the named agent.

Verify access

Start a new chat with the analyst and ask:

Use BigQuery to list datasets in project YOUR_PROJECT_ID, then run select 1 as ok as a smoke test.

For a real validation, ask the agent to query a small known table or view:

select *
from `YOUR_PROJECT.YOUR_DATASET.YOUR_TABLE`
limit 10

If the agent can list datasets and run a small query, the MCP server, credentials, project, and BigQuery IAM permissions are all wired correctly.

Troubleshooting

The agent does not see BigQuery tools

Confirm the BigQuery MCP server is attached to the agent, then start a new chat or restart the runner session. MCP servers load when a session starts.

BigQuery returns permission denied

Google Cloud IAM is missing. Grant roles/bigquery.jobUser on the query project and dataset-level read access such as roles/bigquery.dataViewer.

The project is not set

Set the project in the BigQuery helper or run:

gcloud config set project YOUR_PROJECT_ID

Service account JSON is rejected

Paste the full JSON key file, not a base64-encoded value and not only the private key. The JSON should include fields such as type, project_id, client_email, and private_key.

gcloud login works locally but fails for the agent

Authenticate inside the TeamDay runner environment. Local laptop credentials are separate from the agent runner's credentials.

The agent reports /tmp is not writable

TeamDay runners provide a writable sandbox /tmp and a private durable temp directory for each runner user. If an old session still reports /tmp permission errors, restart the session so it picks up the current runner environment.

Security notes

• Prefer service accounts for production agents.
• Grant read-only dataset access unless the agent explicitly needs write access.
• Use authorized views or separate datasets to restrict sensitive tables.
• Rotate the service account key if it was copied outside TeamDay.
• Remove the BigQuery MCP server from agents that no longer need warehouse access.