Connect your IDE to AlloyDB for PostgreSQL using the MCP Toolbox

This guide shows you how to use the MCP Toolbox for Databases to connect your AlloyDB for PostgreSQL instance to Integrated Development Environments (IDE) and developer tools that support Model Context Protocol (MCP). Use these tools to run SQL queries and interact with your database. This guide is for developers who use their existing IDEs and developer tools to work with AlloyDB.

Model Context Protocol (MCP) is an open protocol for connecting large language models (LLMs) to data sources like AlloyDB. This guide covers how to use MCP Toolbox for Databases to expose your developer assistant tools to a AlloyDB instance using following IDE:

Before you begin

Before you start, make sure you have the required roles.

Required roles

To connect to the instance, you need the following roles or equivalent Identity and Access Management (IAM) permissions

  • Cloud AlloyDB Client (roles/alloydb.client)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Set up the database

  1. Create or select a cluster and its primary instance. These instructions assume your AlloyDB instance has public IP address. By default, AlloyDB assigns a private IP address to a new instance. The MCP Toolbox connects securely to your instance using AlloyDB Language Connectors.

    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.

      Go to project selector

    3. Make sure 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.

      Go to project selector

    5. Make sure that billing is enabled for your Google Cloud project.

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

      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.

  2. Configure Application Default Credentials (ADC) for your environment.

  3. Create or reuse a database user. Be ready to enter the username and password.

Install the MCP Toolbox

  1. 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.6.0 or later:

    linux/amd64

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

    darwin/arm64

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

    darwin/amd64

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

    windows/amd64

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

  2. Make the binary executable:

    chmod +x toolbox

  3. Verify the installation:

    ./toolbox --version

Configure the MCP client

Claude code


1. Install Claude Code.
2. Create .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"
      }
    }
  }
}

4. Restart Claude Desktop.
5. The new chat screen displays a hammer (MCP) icon with the new MCP server.


Cline


1. Open Cline extension in VS Code and tap MCP Servers icon.
2. Tap 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"
      }
    }
  }
}

4. 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: 

{
  "mcp":{
    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"
      }
    }
  }
}

Use Tools

Your AI tool is now connected to AlloyDB using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements.

The following tools are available to the LLM:

  1. list_tables: lists tables and descriptions
  2. execute_sql: execute any SQL statement