Use AlloyDB for PostgreSQL with MCP, Gemini CLI, and other agents

This document describes how to connect your AlloyDB instance to various agents that support the Model Context Protocol (MCP).

We recommend using the dedicated AlloyDB extension for Gemini CLI. The Gemini CLI integrates the underlying MCP server directly into the extension, so you don't need to perform a separate server setup. You can configure Gemini Code Assist to use the Gemini CLI, offering similar setup benefits in your IDE.

Alternatively, other IDEs and agents supporting the MCP can connect through MCP Toolbox for Databases. Toolbox is an open-source MCP server designed to connect AI agents to your data. It handles tasks like authentication and connection pooling, letting you interact with your data with natural language directly from your IDE.

Before you begin

To connect to your AlloyDB instance and use the available tools, you must have one of the following Identity and Access Management (IAM) roles, or a custom role with equivalent permissions:

Task Role name Required Identity and Access Management (IAM) role
Use read-only tools to list and get AlloyDB resources AlloyDB Viewer roles/alloydb.viewer
Connect to an instance and run queries Cloud AlloyDB Client roles/alloydb.client
Service Usage Consumer roles/serviceusage.serviceUsageConsumer
Perform administrative tasks (such as creating or managing clusters, instances, and users) AlloyDB Admin roles/alloydb.admin
Use the observability extension Monitoring Viewer roles/monitoring.viewer

Before you can connect to your AlloyDB instance, complete the following steps to set up your project and database.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the Cloud APIs necessary to create and connect to AlloyDB.

    Enable the APIs

    1. In the Confirm project step, click Next to confirm the name of the project you are going to make changes to.

    2. In the Enable APIs step, click Enable to enable the following:

      • AlloyDB API
      • Compute Engine API
      • Cloud Resource Manager API
      • Service Networking API

      The Service Networking API is required if you plan to configure network connectivity to AlloyDB using a VPC network that resides in the same Google Cloud project as AlloyDB.

      The Compute Engine API and Cloud Resource Manager API are required if you plan to configure network connectivity to AlloyDB using a VPC network that resides in a different Google Cloud project.

  7. Create or select a cluster and its primary instance.
  8. Configure Application Default Credentials (ADC) for your environment.
  9. Create or reuse a database user. Be ready to enter the username and password.

Use the Gemini CLI extensions for AlloyDB

Gemini CLI is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with Data Cloud services and popular open-source databases.

The integration with Gemini CLI is through dedicated extensions that offer additional capabilities compared to a standard MCP Toolbox connection. The following sections describe the alloydb and alloydb-observability extensions, which offer an installation process and a set of tools. The open-source extensions contains detailed information on installation, configuration, and usage examples. For more information, see the Gemini CLI Extension - AlloyDB for PostgreSQL.

The alloydb extension includes tools for querying the database, managing AlloyDB resources, and monitoring database health.

Category Tools Example natural language prompt
Database operations list_tables Show me all the tables in the current database.
execute_sql Run the query: SELECT * FROM products WHERE category = 'electronics';
list_active_queries What queries are running on the database?
get_query_plan Explain the query plan for "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
list_available_extensions What are the available extensions I can install?
list_installed_extensions List all the extensions that are installed.
Resource management
clusters, instances, users		 create_cluster Create an AlloyDB cluster named sales-quarterly-db in the us-east1 region.
get_cluster Get the details for the cluster sales-quarterly-db.
list_clusters List all of my AlloyDB clusters.
create_instance Create a new read instance in the sales-quarterly-db cluster.
get_instance Show me the information for the instance sales-quarterly-db-rp.
list_instances List all instances in the sales-quarterly-db cluster.
create_user Create a new database user named reporting_user.
get_user Get the information for the user reporting_user.
list_users List all database users.
wait_for_operation What is the status of the operation operation-163562789?
Database health & maintenance list_autovacuum_configurations Show me the current autovacuum configuration.
list_memory_configurations What are the current memory configurations for the primary instance?
list_top_bloated_tables List the top five most bloated tables.
list_replication_slots Display all active replication slots.
list_invalid_indexes Check for any invalid indexes in the orders database.

The alloydb-observability extension provides a unified interface for managing and monitoring database performance and health directly from the Gemini CLI.

Category Tools Example natural language prompt
Observability get_system_metrics What are the system metrics, like CPU usage, for the last hour?
get_query_metrics Show me the query performance metrics from the last 15 minutes.

You can use the Gemini CLI extension for AlloyDB in two ways:

  • A standalone command-line tool
  • Integrated into your IDE with Gemini Code Assist

Gemini CLI

  1. Install the Gemini CLI.
  2. Install the AlloyDB extension for Gemini CLI from the GitHub repository using the following command: 
    gemini extensions install https://github.com/gemini-cli-extensions/alloydb
  3. Set environment variables to connect to your AlloyDB instance: 
    export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID"
export ALLOYDB_POSTGRES_REGION="REGION"
export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME"
export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME"
export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"

    The Gemini CLI extension for AlloyDB uses your [application default credentials (ADC)](/authentication/application-default-credentials) for authentication by default. If you want to connect as a database user instead, set the following optional environment variables:

    #Optional: Set for database user authentication
export ALLOYDB_POSTGRES_USER="USERNAME"
export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"

    To connect using a private IP address, you must also set the following environment variable:

    export ALLOYDB_POSTGRES_IP_TYPE="private"
  4. Start the Gemini CLI in interactive mode: 
    gemini
    The CLI automatically loads the AlloyDB extension for Gemini CLI extension and its tools, which you can use to interact with your database.

Gemini Code Assist

We recommend to configure Gemini Code Assist to use the Gemini CLI, this approach removes the need to manually configure an MCP server.

  1. Make sure you have installed and configured the Gemini CLI and the alloydb extension.
  2. Configure Gemini Code Assist to use the Gemini CLI.
  3. Start interacting with your AlloyDB instance using natural language directly within the Gemini Code Assist chat.

Connect with other IDEs using MCP Toolbox for Databases

This section describes how to connect to your AlloyDB instance from various agents using MCP Toolbox for Databases. Toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and your database, providing a control plane for your AI tools. This section provides instructions for connecting to an AlloyDB instance using either a public or private IP address. By default, Toolbox uses a public IP address, but you can configure a private IP connection by setting the ALLOYDB_POSTGRES_IP_TYPE environment variable as shown in the configuration examples. For more information about using the MCP Toolbox, see Create AlloyDB Database with MCP Toolbox.

Install MCP Toolbox for Databases

To connect your IDE to AlloyDB, you must install MCP Toolbox for Databases, an open-source server that connects AI agents to your data.

  1. Download the latest version of Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use Toolbox version v0.15.0 or later.

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox

  2. Make the binary an executable.

    chmod +x toolbox

  3. Verify the installation.

    ./toolbox --version

Configure your client

Select your agent tool from the following options:

Claude code

  1. Install Claude Code.
  2. Create the .mcp.json file in your project root, if it doesn't exist.
  3. Add the configuration, replace the environment variables with your values, and save.

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude desktop

  1. Open Claude Desktop and navigate to Settings.
  2. In the Developer tab, click Edit Config to open the configuration file.
  3. Add the configuration, replace the environment variables with your values, and save.

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
  1. Restart Claude Desktop.
  2. The new chat screen displays a hammer (MCP) icon with the new MCP server.

Cline

  1. Open the Cline extension in VS Code and tap MCP Servers icon.
  2. Click Configure MCP Servers to open the configuration file.
  3. Add the following configuration, replace the environment variables with your values, and save.

{
  "mcpServers": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

A green active status appears after the server connects successfully.

Cursor

  1. Create the .cursor directory in your project root if it doesn't exist.
  2. Create the .cursor/mcp.json file if it doesn't exist, and open it.
  3. Add the following configuration, replace the environment variables with your values, and save.
{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
  1. Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)

  1. Open VS Code and create .vscode directory in your project root if it does not exist.
  2. Create the .vscode/mcp.json file if it doesn't exist, and open it.
  3. Add the following configuration, replace the environment variables with your values, and save.
{
  "servers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
        "ALLOYDB_POSTGRES_REGION": "REGION",
        "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
        "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
        "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
        "ALLOYDB_POSTGRES_USER": "USERNAME",
        "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Windsurf

  1. Open Windsurf and navigate to Cascade assistant.
  2. Click the MCP icon, then click Configure to open the configuration file.
  3. Add the following configuration, replace the environment variables with your values, and save.
{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}