Create an AlloyDB database using the MCP Toolbox in IDE

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:

Before you begin

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

  2. Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.

  3. Enable the AlloyDB Admin API.

    Enable the 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

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

  2. Make the binary an executable.

    chmod +x toolbox

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

  1. Install Claude Code.
  2. Create a .mcp.json file in your project root, if it doesn't exist.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.
  1. Add the following configuration, replace API_KEYwith 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

  1. Open Claude Desktop and navigate to Settings.
  2. In the Developer tab, click Edit Config to open the configuration file.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.

  1. 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

  1. Open Cline extension in VS Code and tap MCP Servers icon.
  2. Tap Configure MCP Servers to open the configuration file.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.

  1. 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

  1. Create the .cursor directory in your project root if it does not exist.
  2. Create the .cursor/mcp.json file if it doesn't exist, and open it.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.
  1. 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)

  1. Open VS Code and create a .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. Generate an access token to use as API_KEY by running gcloud auth print-access-token.
  1. 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

  1. Open Windsurf and navigate to the Cascade assistant.
  2. Click the MCP icon, then click Configure to open the configuration file.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.

  1. 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

  1. Install the Gemini CLI.
  2. In your working directory, create a folder named .gemini. Within it, create a settings.json file.
  3. Generate an access token to use as API_KEY by running gcloud auth print-access-token.

  1. 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

  1. Install the Gemini Code Assist extension in Visual Studio Code.
  2. Enable Agent Mode in Gemini Code Assist chat.
  3. In your working directory, create a folder named .gemini. Within it, create a settings.json file.
  4. Generate an access token to use as API_KEY by running gcloud auth print-access-token.

  1. 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, or SECONDARY).
  • alloydb-create-user: creates ALLOYDB_BUILT_IN or IAM-based users for an AlloyDB cluster.
  • alloydb-get-operation: polls the operations API until the operation is done.
  • alloydb-list-clusters: lists clusters in a given project and location.
  • alloydb-list-instances: lists instances in a given project and location.
  • alloydb-list-users: lists users in a given project and location.

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.