Usar o AlloyDB Omni com o MCP, a CLI do Gemini e outros agentes

Neste documento, descrevemos como conectar sua instância do AlloyDB Omni a vários agentes que oferecem suporte ao Protocolo de Contexto de Modelo (MCP).

Como o AlloyDB Omni é compatível com o PostgreSQL, você pode usar ferramentas e extensões projetadas para o PostgreSQL.

Para a configuração mais simples, use a extensão dedicada do PostgreSQL para a CLI do Gemini. Ela integra o servidor MCP subjacente diretamente à extensão, para que você não precise realizar uma configuração separada do servidor. Você pode configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo benefícios de configuração semelhantes no seu ambiente de desenvolvimento integrado.

Como alternativa, outros IDEs e agentes que oferecem suporte ao MCP podem se conectar usando a MCP Toolbox for Databases. A Toolbox é um servidor MCP de código aberto projetado para conectar agentes de IA aos seus dados. Ele processa tarefas como autenticação e pool de conexões, permitindo que você interaja com seus dados usando linguagem natural diretamente do seu ambiente de desenvolvimento integrado.

Antes de começar

Antes de se conectar à sua instância do AlloyDB Omni, faça o seguinte:

  1. Instale o AlloyDB Omni para Kubernetes ou AlloyDB Omni para contêineres e tenha uma instância de banco de dados em execução.
  2. Crie ou reutilize um usuário de banco de dados. Tenha o nome de usuário e a senha em mãos.

Usar a extensão da CLI do Gemini para PostgreSQL

A CLI do Gemini é um agente de IA de código aberto projetado para ajudar nos fluxos de trabalho de desenvolvimento, auxiliando na programação, depuração, análise de dados e criação de conteúdo. A missão dele é fornecer uma interface de agente para interagir com os serviços da Data Cloud e bancos de dados de código aberto conhecidos.

A integração com a CLI do Gemini para o AlloyDB Omni é feita pela extensão do PostgreSQL. Essa extensão oferece um conjunto de ferramentas para interagir com o PostgreSQL e o AlloyDB Omni, permitindo gerenciar bancos de dados, executar consultas e explorar esquemas diretamente na CLI do Gemini usando comandos de linguagem natural.

Os exemplos a seguir usam um banco de dados ecommerce de amostra com estas tabelas:

  • products: contém informações do produto, incluindo product_id, product_name, category e price.
  • customers: armazena dados de clientes, como customer_id, first_name, last_name e email.
  • orders: contém informações do pedido, incluindo order_id, customer_id e order_date.

As seguintes ferramentas estão disponíveis na extensão do PostgreSQL:

Categoria Ferramenta Exemplo de comando de linguagem natural
Operações de banco de dados execute_sql Mostre os 10 produtos mais caros na categoria "Notebooks".
get_query_plan Explique o plano de consulta para uma consulta que encontra todos os clientes que não fizeram um pedido nos últimos seis meses.
list_active_queries Quais consultas estão sendo executadas no banco de dados?
database_overview Me dê uma visão geral do banco de dados atual.
list_tables Mostre todas as tabelas no banco de dados atual.
list_views Quais visualizações estão disponíveis?
list_schemas Liste todos os esquemas.
list_triggers Mostre os gatilhos na tabela de pedidos.
list_available_extensions Quais extensões estão disponíveis para instalação?
list_installed_extensions Liste todas as extensões instaladas.
list_indexes Listar todos os índices.
list_sequences Liste todas as sequências.
Integridade e manutenção do banco de dados list_autovacuum_configurations Mostre a configuração atual do autovacuum.
list_memory_configurations Quais são as configurações de memória atuais?
list_top_bloated_tables Liste as cinco tabelas mais inchadas.
list_replication_slots Mostra todos os slots de replicação ativos.
list_invalid_indexes Verifique se há índices inválidos no banco de dados ecommerce.
long_running_transactions Mostre as transações de longa duração.
list_locks Listar todos os bloqueios.
replication_stats Mostre as estatísticas de replicação.

Você pode usar a extensão da CLI do Gemini para PostgreSQL de duas maneiras:

  • Uma ferramenta de linha de comando independente
  • Integrado ao seu ambiente de desenvolvimento integrado com o Gemini Code Assist

CLI do Gemini

  1. Instale a CLI do Gemini (versão 0.6.0 ou mais recente).
  2. Instale a extensão do PostgreSQL para a CLI do Gemini no repositório do GitHub usando o comando a seguir: 
    gemini extensions install https://github.com/gemini-cli-extensions/postgres
  3. Defina variáveis de ambiente para se conectar à instância do AlloyDB Omni: 
    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"

    Também é possível carregar essas variáveis de um arquivo .env no diretório de trabalho.

  4. Inicie a CLI do Gemini no modo interativo: 
    gemini
     A CLI carrega automaticamente a extensão do PostgreSQL e as ferramentas dela, que podem ser usadas para interagir com o banco de dados.

Gemini Code Assist

Para evitar a configuração manual de um servidor MCP, configure o Gemini Code Assist para usar a CLI do Gemini.

  1. Instale e configure a CLI do Gemini e a extensão postgres conforme descrito na guia "CLI do Gemini".
  2. Configure o Gemini Code Assist para usar a CLI do Gemini.
  3. Comece a interagir com sua instância do AlloyDB Omni usando linguagem natural diretamente no chat do Gemini Code Assist.

Conectar-se a outros ambientes de desenvolvimento integrado usando a MCP Toolbox para bancos de dados

Esta seção descreve como se conectar à instância do AlloyDB Omni de vários agentes usando a Caixa de ferramentas do MCP para bancos de dados.

Instalar a MCP Toolbox para bancos de dados

Para conectar seu ambiente de desenvolvimento integrado ao AlloyDB Omni, instale o MCP Toolbox for Databases, um servidor de código aberto que conecta agentes de IA aos seus dados.

  1. Faça o download da versão mais recente da caixa de ferramentas como um binário. Selecione o binário correspondente ao seu sistema operacional e à arquitetura da CPU.

    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. Torne o binário executável.

    chmod +x toolbox

  3. Verifique a instalação.

    ./toolbox --version

Configurar o cliente

Selecione sua ferramenta de agente entre as seguintes opções:

Cursor

  1. Crie o diretório .cursor na raiz do projeto, se ele não existir.
  2. Crie o arquivo .cursor/mcp.json, se ele não existir, e abra-o.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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"
      }
    }
  }
}
  1. Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Windsurf

  1. Abra o Windsurf e navegue até o assistente do Cascade.
  2. Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se ele não existir.
  2. Crie o arquivo .vscode/mcp.json, se ele não existir, e abra-o.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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. Abra a extensão Cline no VS Code e clique no ícone Servidores MCP.
  2. Clique em Configurar servidores MCP para abrir o arquivo de configuração.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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"
      }
    }
  }
}
  1. Um status ativo verde aparece depois que o servidor se conecta.

Claude para computador

  1. Abra o Claude para computador e acesse Configurações.
  2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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"
      }
    }
  }
}
  1. Reinicie o Claude Desktop.
  2. A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP.

Código do Claude

  1. Instale o Claude Code.
  2. Crie o arquivo .mcp.json na raiz do projeto, se ele não existir.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "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"
      }
    }
  }
}
  1. Reinicie o código do Claude para aplicar a nova configuração.