How many times a day do you leave Antigravity just to run a database query? Open the BigQuery console, write the SQL, copy the result, jump back to the editor. It's a small friction — but it adds up over the course of a development week.
In April 2026, Google released MCP Toolbox for Databases v1.0.0, an open-source MCP server that lets Antigravity agents connect directly to BigQuery, AlloyDB, Spanner, Cloud SQL, and more. The result: you stay in the editor, ask the agent in plain English, and it handles the query round-trip for you.
This guide walks through the complete setup and the usage patterns I've found most useful in day-to-day development.
What Is MCP Toolbox for Databases?
MCP Toolbox for Databases is an open-source MCP server maintained by Google. It implements the Model Context Protocol spec, exposing database operations as callable tools that Antigravity agents can invoke.
The v1.0.0 release (April 2026) supports the following databases:
- AlloyDB for PostgreSQL
- BigQuery
- Bigtable
- Cloud SQL (MySQL / PostgreSQL / SQL Server)
- Spanner
- Looker
- Standard MySQL, PostgreSQL, Neo4j, and Dgraph
What makes v1.0.0 meaningful for production use is the authentication model. Connections go through Application Default Credentials (ADC) or a service account — no token management required, no credentials hardcoded into config files. For teams where database access is tied to IAM roles, this is a significant improvement over rolling your own MCP server.
The project is actively maintained by Google engineers and has a clear versioning policy, which matters when you're wiring it into a team's development workflow.
Setup via the Antigravity MCP Store
The fastest path is through Antigravity's built-in MCP Store:
- Open Antigravity and click the "..." icon at the top of the left panel
- Select "MCP Servers"
- Search for "mcp-toolbox"
- Select MCP Toolbox for Databases and install
After installation, your ~/.antigravity/mcp.json (or .antigravity/mcp.json in the project) is updated automatically:
{
"mcpServers": {
"mcp-toolbox": {
"command": "toolbox",
"args": ["--config", "${workspaceFolder}/.toolbox/tools.yaml"],
"env": {
"GOOGLE_CLOUD_PROJECT": "${env:GOOGLE_CLOUD_PROJECT}"
}
}
}
}Next, create .toolbox/tools.yaml in your project root to define your database connections and tools.
Connecting to BigQuery: A Working Configuration
Here's a tools.yaml for BigQuery that covers the two most common use cases — running arbitrary queries and inspecting table schemas:
sources:
my-bigquery:
kind: bigquery
project: your-gcp-project-id
tools:
run-query:
kind: bigquery-sql
source: my-bigquery
description: "Execute a SQL query against BigQuery"
statement: |
${sql}
parameters:
- name: sql
type: string
description: "The SQL query to execute"
get-schema:
kind: bigquery-sql
source: my-bigquery
description: "Get column information for a specific table"
statement: |
SELECT column_name, data_type, is_nullable, description
FROM `your-gcp-project-id`.INFORMATION_SCHEMA.COLUMNS
WHERE table_name = '${table_name}'
ORDER BY ordinal_position
parameters:
- name: table_name
type: string
description: "The table name to inspect"Make sure you've run gcloud auth application-default login locally. The toolbox picks up ADC automatically — no extra config needed.
Once set up, you can ask the agent naturally:
/agent: Check the schema of the users table and tell me
which columns have the most NULL values
The agent calls get-schema, inspects the structure, generates a NULL-counting query, runs it through run-query, and summarizes the findings. Three manual steps become a single instruction — and the agent has the schema context for any follow-up questions in the same session.
Connecting to AlloyDB for PostgreSQL
AlloyDB requires the cluster endpoint in addition to the project ID. Here's a working configuration:
sources:
my-alloydb:
kind: alloydb-postgres
project: your-gcp-project-id
region: us-central1
cluster: your-cluster-name
instance: your-instance-name
database: your-database-name
user: your-db-user
password: ${env:DB_PASSWORD}
tools:
run-alloydb-query:
kind: postgres-sql
source: my-alloydb
description: "Execute a SQL query against AlloyDB"
statement: |
${sql}
parameters:
- name: sql
type: string
description: "The SQL query to execute"
inspect-alloydb-table:
kind: postgres-sql
source: my-alloydb
description: "Get column and constraint info for a table"
statement: |
SELECT
c.column_name,
c.data_type,
c.is_nullable,
c.column_default,
tc.constraint_type
FROM information_schema.columns c
LEFT JOIN information_schema.key_column_usage kcu
ON c.table_name = kcu.table_name
AND c.column_name = kcu.column_name
LEFT JOIN information_schema.table_constraints tc
ON kcu.constraint_name = tc.constraint_name
WHERE c.table_name = '${table_name}'
ORDER BY c.ordinal_position
parameters:
- name: table_name
type: string
description: "The table to inspect"The password reads from an environment variable. Keep your .toolbox/tools.yaml in version control — just make sure .env is in .gitignore so credentials don't end up in the repo.
Connecting to Spanner
Spanner uses a slightly different connection model based on instance and database IDs:
sources:
my-spanner:
kind: spanner
project: your-gcp-project-id
instance: your-instance-id
database: your-database-id
tools:
spanner-query:
kind: spanner-sql
source: my-spanner
description: "Execute a Spanner SQL query"
statement: |
${sql}
parameters:
- name: sql
type: string
description: "SQL query to run"Spanner's SQL dialect is close to standard SQL but has a few quirks — for example, it uses backtick-quoted identifiers rather than double quotes. If your agent generates queries that fail, telling it "this is Spanner SQL, not standard PostgreSQL" in the session prompt usually resolves the issue quickly.
Agent Patterns That Actually Pay Off
Once the toolbox is running, a few workflows deliver disproportionate value:
Schema-to-TypeScript generation: Ask the agent to "look at the orders table schema and generate TypeScript types with JSDoc comments." It fetches the live schema and writes the types directly — no more schema drift between your database and application code. This is one of those tasks where the agent's output is immediately usable without editing.
Migration impact analysis: Before altering a column, ask: "If I change user_id from integer to UUID, which tables and foreign keys would be affected?" The agent queries the information schema, counts references, and gives you a report before you touch anything. I've caught three cascading-update issues this way before writing a single line of migration code.
Data quality audit: "Find users registered last month with a missing or duplicate email" — the agent translates this to SQL, runs it, and presents the results in a readable format. These ad-hoc audits used to mean context-switching to a console; now they stay inside the editor flow.
Exploratory analysis for feature work: When starting work on a new feature that touches an unfamiliar table, I'll ask the agent to summarize the table structure, common value distributions, and any obvious data quality issues. It's a faster onboarding step than reading someone else's schema documentation.
For an overview of how MCP fits into the broader Antigravity ecosystem, see the MCP ecosystem guide.
Two Common Setup Errors
Application Default Credentials not found
Error: google.auth.exceptions.DefaultCredentialsError:
Could not automatically determine credentials.
Run gcloud auth application-default login for local development. In CI/CD environments, set GOOGLE_APPLICATION_CREDENTIALS to point to a service account key file. If you're running inside Cloud Shell or a GCE instance, the environment credentials are picked up automatically — no extra step needed.
BigQuery quota exceeded
Error: 403 Quota exceeded for quota metric 'queries'
During development, always include a LIMIT clause in your exploratory queries. You can also set max_rows in the toolbox config to cap how many rows any single tool call returns — useful as a guardrail when the agent runs queries autonomously without a specific row limit in the SQL.
Security Considerations for Production Use
A few principles worth establishing before you connect agents to production databases:
Use read-only credentials by default. Create a dedicated service account with roles/bigquery.dataViewer (or equivalent) for the MCP Toolbox connection. Reserve write access for specific tools that need it, and document why. An agent that can accidentally DELETE production rows is a risk you probably want to avoid.
Scope tools by environment. In your CI pipeline or staging environment, maintain a separate tools.yaml that points to a test dataset. This way, agent-assisted development never accidentally touches production data during a debugging session.
Log tool calls. The MCP Toolbox writes structured logs for each tool invocation. Piping these to Cloud Logging gives you an audit trail — useful when you want to understand what queries the agent ran during a refactoring session.
Where to Start
The lowest-friction entry point: pick one table you query frequently — the one where you always open the console "just to check something" — and add a get-schema tool for it. That single step removes an entire category of context-switching.
For building custom tools on top of the toolbox, the MCP server build guide covers the construction patterns in depth. Once you're comfortable with database reads, expanding to writes — with appropriate guardrails — opens the door to agent-assisted migrations and automated data pipeline monitoring.