Quick Start: Prebuilt Tools
Stop context-switching and let your AI assistant become a true co-developer. By connecting your IDE to your databases with MCP Toolbox, you can query your data in plain English, automate schema discovery and management, and generate database-aware code.
You can use the Toolbox in any MCP-compatible IDE or client (e.g., Gemini CLI, Google Antigravity, Claude Code, Codex, etc.) by configuring the MCP server.
Prebuilt tools are also conveniently available via the Google Antigravity MCP Store with a simple click-to-install experience.
-
Add the following to your client's MCP configuration file (usually mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"toolbox-postgres": {
"command": "npx",
"args": [
"-y",
"@toolbox-sdk/server",
"--prebuilt=postgres",
"--stdio"
]
}
}
}
-
Set the appropriate environment variables to connect, see the Prebuilt Tools Reference.
When you run Toolbox with a --prebuilt=<database> flag, you instantly get access to standard tools to interact with that database. You can also specify a specific toolset using the --prebuilt=<database>/<toolset> syntax (e.g., --prebuilt=postgres/data to only load SQL tools).
Supported databases currently include:
- Google Cloud: AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore, Knowledge Catalog (formerly known as Dataplex).
- Other Databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake, Trino, and more.
For a full list of available tools and their capabilities across all supported databases, see the Prebuilt Tools Reference.
See the Install & Run the Toolbox server section for different execution methods like Docker or binaries.
[!TIP]
For users looking for a managed solution, Google Cloud MCP Servers
provide a managed MCP experience with prebuilt tools; you can learn more about the differences here.
Quick Start: Custom Tools
Toolbox can also be used as a framework for customized tools.
The primary way to configure Toolbox is through the tools.yaml file. If you
have multiple files, you can tell Toolbox which to load with the --config tools.yaml flag.
You can find more detailed reference documentation to all resource types in the
Resources.
Sources
The sources section of your tools.yaml defines what data sources your
Toolbox should have access to. Most tools will have at least one source to
execute against.
kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password
For more details on configuring different types of sources, see the
Sources.
Tools
The tools section of a tools.yaml define the actions an agent can take: what
type of tool it is, which source(s) it affects, what parameters it uses, etc.
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
For more details on configuring different types of tools, see the
Tools.
Toolsets
The toolsets section of your tools.yaml allows you to define groups of tools
that you want to be able to load together. This can be useful for defining
different groups based on agent or application.
kind: toolset
name: my_first_toolset
tools:
- my_first_tool
- my_second_tool
---
kind: toolset
name: my_second_toolset
tools:
- my_second_tool
- my_third_tool
Prompts
The prompts section of a tools.yaml defines prompts that can be used for
interactions with LLMs.
kind: prompt
name: code_review
description: "Asks the LLM to analyze code quality and suggest improvements."
messages:
- content: >
Please review the following code for quality, correctness,
and potential improvements: \n\n{{.code}}
arguments:
- name: "code"
description: "The code to review"
For more details on configuring prompts, see the
Prompts.
Resources
The resources and resourceTemplates sections of your tools.yaml define read-only
content, files, or parameterized directory trees that can be discovered and retrieved
by MCP clients:
kind: resource
name: database_schema_ddl
type: text
description: "Core table definitions and constraints."
mimeType: text/x-sql
text: |
CREATE TABLE customers (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
);
---
kind: resource
name: database_schema
type: file
description: "PostgreSQL schema definition."
path: "./schema.sql"
---
kind: resourceTemplate
name: server_logs
type: file
description: "Application log files."
uriTemplate: "file:///var/log/{path}"
allowedPaths:
- "/var/log"
For more details on configuring resources and resource templates, see
Resources.
Install & Run the Toolbox server
You can run Toolbox directly with a configuration file:
npx @toolbox-sdk/server --config tools.yaml
This runs the latest version of the Toolbox server with your configuration file.
[!NOTE]
This method is optimized for convenience rather than performance.
For a more standard and reliable installation, please use the binary
or container image as described in Install & Run the Toolbox server.
Install Toolbox
For the latest version, check the releases page and use the
following instructions for your OS and CPU architecture.
To install Toolbox as a binary:
To install Toolbox as a binary on Linux (AMD64):
# see releases page for other versions
export VERSION=1.14.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
To install Toolbox as a binary on macOS (Apple Silicon):
# see releases page for other versions
export VERSION=1.14.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox
To install Toolbox as a binary on macOS (Intel):
# see releases page for other versions
export VERSION=1.14.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox
To install Toolbox as a binary on Windows (Command Prompt):
:: see releases page for other versions
set VERSION=1.14.0
curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/amd64/toolbox.exe"
To install Toolbox as a binary on Windows (PowerShell):
# see releases page for other versions
$VERSION = "1.14.0"
curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/amd64/toolbox.exe"
To install Toolbox as a binary on Windows ARM64 (Command Prompt):
:: see releases page for other versions
set VERSION=1.14.0
curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/arm64/toolbox.exe"
To install Toolbox as a binary on Windows ARM64 (PowerShell):
# see releases page for other versions
$VERSION = "1.14.0"
curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/arm64/toolbox.exe"
# see releases page for other versions
export VERSION=1.14.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
To install Toolbox using Homebrew on macOS or Linux:
brew install mcp-toolbox
To install from source, ensure you have the latest version of
Go installed, and then run the following command:
go install github.com/googleapis/mcp-toolbox@v1.14.0
# Install Gemini CLI
npm install -g @google/gemini-cli
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgres
# Run Gemini CLI
gemini
Interact with your custom tools using natural language through the Gemini CLI.
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox