This page describes how to use the MCP Toolbox for Databases to create and manage your AlloyDB for PostgreSQL clusters and instances from integrated development environments (IDEs). You can use developer tools that support the Model Context Protocol (MCP).
Model Context Protocol (MCP) is an open protocol for connecting large language models (LLMs) to data sources and APIs like the AlloyDB Admin API. An AI assistant is an LLM-powered chat interface in your IDE that helps you achieve your goals and complete tasks. This page describes how to use the MCP Toolbox for Databases to expose your developer assistant tools to a AlloyDB instance using the following IDEs:
- Cursor
- Windsurf (Codium)
- Visual Studio Code (Copilot)
- Cline (VS Code extension)
- Claude desktop
- Claude code
- Gemini CLI
- Gemini Code Assist
Before you begin
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.
Enable the AlloyDB Admin API.
Required roles
To manage AlloyDB resources, ask your administrator to grant you the following Identity and Access Management roles on your project:
- AlloyDB Admin (
roles/alloydb.admin
). - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer
).
Install the MCP Toolbox
Download the latest version of the MCP Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use MCP Toolbox version V0.10.0 or later.
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.10.0/linux/amd64/toolbox
darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/v0.10.0/darwin/arm64/toolbox
darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.10.0/darwin/amd64/toolbox
windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.10.0/windows/amd64/toolbox
Make the binary an executable.
chmod +x toolbox
Verify the installation.
./toolbox --version
Configure the MCP client
You can configure your IDE to use the control plane tools to create and manage AlloyDB clusters and instances. If you already have an AlloyDB instance, skip this step and go to Connect your IDE to AlloyDB for PostgreSQL using the MCP Toolbox. Instances are created with a public IP address using the given control plane tools. Add the following configuration to your IDE's MCP settings file. This approach exposes the alloydb-postgres-admin
tool to your AI assistant.
Claude code
- Install Claude Code.
- Create a
.mcp.json
file in your project root, if it doesn't exist. - Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and save.
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Claude desktop
- Open Claude Desktop and navigate to Settings.
- In the Developer tab, click Edit Config to open the configuration file.
- Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and save.
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Cline
- Open Cline extension in VS Code and tap MCP Servers icon.
- Tap Configure MCP Servers to open the configuration file.
- Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and save.
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Cursor
- Create the
.cursor
directory in your project root if it does not exist. - Create the
.cursor/mcp.json
file if it doesn't exist, and open it. - Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace the
API_KEY
with the generated token, and save:
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Visual Studio Code (Copilot)
- Open VS Code and create a
.vscode
directory in your project root if it does not exist. - Create the
.vscode/mcp.json
file if it doesn't exist, and open it. - Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and save.
{ "mcp":{ "servers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } } }
Windsurf
- Open Windsurf and navigate to the Cascade assistant.
- Click the MCP icon, then click Configure to open the configuration file.
- Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and save.
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Gemini CLI
- Install the Gemini CLI.
- In your working directory, create a folder named
.gemini
. Within it, create asettings.json
file. - Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and then save.
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Gemini Code Assist
- Install the Gemini Code Assist extension in Visual Studio Code.
- Enable Agent Mode in Gemini Code Assist chat.
- In your working directory, create a folder named
.gemini
. Within it, create asettings.json
file. - Generate an access token to use as
API_KEY
by runninggcloud auth print-access-token
.
- Add the following configuration, replace
API_KEY
with the generated token, and then save:
{ "mcpServers": { "alloydb-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "alloydb-postgres-admin", "--stdio"], "env": { "API_KEY": "API_KEY" } } } }
Your AI tool is now connected to the AlloyDB for PostgreSQL control plane using MCP. Ask your AI assistant to create a cluster or instance.
Use administrator tools
The following tools are available to the LLM:
- alloydb-create-cluster: creates an AlloyDB cluster.
- alloydb-create-instance: creates an AlloyDB instance (
PRIMARY
,READ_POOL
, orSECONDARY
). - alloydb-get-operation: polls the operations API until the operation is done.
Connect to your data
After you set up an AlloyDB cluster and instance, you can connect your IDE to the database to query your data. For more information, see Connect your IDE to AlloyDB using the MCP Toolbox.