Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">16.8.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/connect-ide-using-mcp-toolbox.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.10.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.9.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.7.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.5.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.14.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.13.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.11.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.9.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.8.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [15.18.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.18.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [15.17.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.17.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [15.15.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.15.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [15.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.13.0/docs/connect-ide-using-mcp-toolbox.md.txt)
- [15.12.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.12.0/docs/connect-ide-using-mcp-toolbox.md.txt)

<br />

This document describes how to connect your AlloyDB Omni instance to various agents that support the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).

<br />

Since AlloyDB Omni is PostgreSQL compatible, you can use tools and extensions designed for PostgreSQL.

For the simplest setup, use the dedicated PostgreSQL extension for [Gemini CLI](https://docs.cloud.google.com/gemini/docs/codeassist/gemini-cli.md.txt); it 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](https://github.com/googleapis/genai-toolbox). 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

Before you connect to your AlloyDB Omni instance, make sure to do the following:

1. [Install AlloyDB Omni on Kubernetes](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.8.0/docs/deploy-kubernetes.md.txt) and have a running database instance.
2. Create or reuse a database user. Be ready to enter the username and password.

## Use the Gemini CLI extension for PostgreSQL

> [!NOTE]
> **Note:** The PostgreSQL Gemini CLI extension is based on MCP Toolbox for Databases. MCP Toolbox for Databases is in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0).

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 for AlloyDB Omni is through the [PostgreSQL extension](https://github.com/gemini-cli-extensions/postgres). This extension provides a set of tools to interact with PostgreSQL and AlloyDB Omni allowing you to manage your databases, execute queries, and explore schemas directly from the Gemini CLI using natural language prompts.

The following examples use a sample `ecommerce` database with the following tables:

- `products`: contains product information, including `product_id`, `product_name`, `category`, and `price`.
- `customers`: stores customer data, such as `customer_id`, `first_name`, `last_name`, and `email`.
- `orders`: holds order information, including `order_id`, `customer_id`, and `order_date`.

The following tools are available within the PostgreSQL extension:

| Category | Tool | Example natural language prompt |
|---|---|---|
| Database operations | `execute_sql` | Show me the 10 most expensive products in the 'Laptops' category. |
| Database operations | `get_query_plan` | Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months. |
| Database operations | `list_active_queries` | What queries are running on the database? |
| Database operations | `database_overview` | Give me an overview of the current database. |
| Database operations | `list_tables` | Show me all the tables in the current database. |
| Database operations | `list_views` | What views are available? |
| Database operations | `list_schemas` | List all schemas. |
| Database operations | `list_triggers` | Show me the triggers on the orders table. |
| Database operations | `list_available_extensions` | What are the available extensions I can install? |
| Database operations | `list_installed_extensions` | List all the extensions that are installed. |
| Database operations | `list_indexes` | List all indexes. |
| Database operations | `list_sequences` | List all sequences. |
| Database health and maintenance | `list_autovacuum_configurations` | Show me the current autovacuum configuration. |
| Database health and maintenance | `list_memory_configurations` | What are the current memory configurations? |
| Database health and maintenance | `list_top_bloated_tables` | List the top five most bloated tables. |
| Database health and maintenance | `list_replication_slots` | Display all active replication slots. |
| Database health and maintenance | `list_invalid_indexes` | Check for any invalid indexes in the `ecommerce` database. |
| Database health and maintenance | `long_running_transactions` | Show me the long running transactions. |
| Database health and maintenance | `list_locks` | List all locks. |
| Database health and maintenance | `replication_stats` | Show me the replication stats. |

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

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

### Gemini CLI

1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-installation) (version 0.6.0 or later).
2. Install the PostgreSQL extension for Gemini CLI from the GitHub repository using the following command:

   ```
   gemini extensions install https://github.com/gemini-cli-extensions/postgres
   ```
3. Set environment variables to connect to your AlloyDB Omni instance:

   ```
   export POSTGRES_HOST="DATABASE_HOST"
   export POSTGRES_PORT="DATABASE_PORT"
   export POSTGRES_DATABASE="DATABASE_NAME"
   export POSTGRES_USER="DATABASE_USER"
   export POSTGRES_PASSWORD="DATABASE_PASSWORD"
   ```

   You can also load these variables from a `.env` file in your working directory.
4. Start the Gemini CLI in interactive mode:

   ```
   gemini
   ```
   The CLI automatically loads the PostgreSQL extension and its tools, which you can use to interact with your database.

### Gemini Code Assist

To avoid manually configuring an MCP server, configure Gemini Code Assist to use the Gemini CLI.

1. Install and configure the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-installation) and the [`postgres` extension](https://github.com/gemini-cli-extensions/postgres) as described in the Gemini CLI tab.
2. [Configure Gemini Code Assist to use the Gemini CLI](https://developers.google.com/gemini-code-assist/docs/set-up-gemini-standard-enterprise).
3. Start interacting with your AlloyDB Omni 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 Omni instance from various agents using [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox).

### Install MCP Toolbox for Databases

To connect your IDE to AlloyDB Omni, 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](https://github.com/googleapis/genai-toolbox/releases) corresponding to your operating system (OS) and CPU architecture.

   ### linux/amd64

   ```
   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/linux/amd64/toolbox
   ```

   ### darwin/arm64

   ```
   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/arm64/toolbox
   ```

   ### darwin/amd64

   ```
   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/amd64/toolbox
   ```

   ### windows/amd64

   ```
   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/windows/amd64/toolbox.exe
   ```
2. Make the binary an executable.

   ```bash
   chmod +x toolbox
   ```
3. Verify the installation.

   ```bash
   ./toolbox --version
   ```

### Configure your client

Select your agent tool from the following options:

### 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
```

4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings \> Cursor Settings \> MCP**. A green active status appears when the server connects.

### Windsurf

1. Open [Windsurf](https://docs.codeium.com/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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
```

### Visual Studio Code (Copilot)

1. Open [VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
```

### Cline

1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and click **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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
      
```

4. A green active status appears after the server connects successfully.

### Claude desktop

1. Open [Claude Desktop](https://claude.ai/download) 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
```

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

### Claude code

1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview).
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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
```

4. Restart Claude code to apply the new configuration.