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

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

Recomendamos usar a extensão dedicada do AlloyDB para a CLI do Gemini. A CLI do Gemini integra o servidor MCP subjacente diretamente à extensão, então não é necessário fazer 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 caixa de ferramentas é 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

Para se conectar à sua instância do AlloyDB e usar as ferramentas disponíveis, você precisa ter um dos seguintes papéis do Identity and Access Management (IAM) ou um papel personalizado com permissões equivalentes:

Tarefa Nome do papel Papel necessário do Identity and Access Management (IAM)
Usar ferramentas somente leitura para listar e receber recursos do AlloyDB Leitor do AlloyDB roles/alloydb.viewer
Conectar-se a uma instância e executar consultas Cliente do Cloud AlloyDB roles/alloydb.client
Consumidor do Service Usage roles/serviceusage.serviceUsageConsumer
Realizar tarefas administrativas, como criar ou gerenciar clusters, instâncias e usuários Administrador do AlloyDB roles/alloydb.admin
Usar a extensão de observabilidade Visualizador de monitoramento roles/monitoring.viewer

Antes de se conectar à instância do AlloyDB, conclua as etapas a seguir para configurar o projeto e o banco de dados.

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  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 role (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 role (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. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB.

    Ativar as APIs

    1. Na etapa Confirmar projeto, clique em Próxima para confirmar o nome do projeto em que você vai fazer mudanças.

    2. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:

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

      A API Service Networking é necessária se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside no mesmo projeto Google Cloud do AlloyDB.

      As APIs Compute Engine e Cloud Resource Manager são necessárias se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside em um projeto Google Cloud diferente.

  7. Crie ou selecione um cluster e a instância principal dele.
  8. Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.
  9. Crie ou reutilize um usuário de banco de dados. Tenha o nome de usuário e a senha em mãos.

Usar as extensões da CLI do Gemini para o AlloyDB

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 é feita por extensões dedicadas que oferecem recursos adicionais em comparação com uma conexão padrão da caixa de ferramentas do MCP. As seções a seguir descrevem as extensões alloydb e alloydb-observability, que oferecem um processo de instalação e um conjunto de ferramentas. As extensões de código aberto contêm informações detalhadas sobre instalação, configuração e exemplos de uso. Para mais informações, consulte Extensão da CLI do Gemini: AlloyDB para PostgreSQL.

Extensão do AlloyDB

A extensão alloydb inclui ferramentas para consultar o banco de dados, gerenciar recursos do AlloyDB e monitorar a integridade do banco de dados.

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 do cliente, como customer_id, first_name, last_name e email.
  • orders: contém informações do pedido, incluindo order_id, customer_id e order_date.
Categoria Ferramentas Exemplo de comando em linguagem natural
Operações de 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.
execute_sql Mostre os 10 produtos mais caros na categoria "Notebooks".
list_active_queries Quais consultas estão sendo executadas no banco de dados?
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_available_extensions Quais extensões estão disponíveis para instalação?
list_installed_extensions Liste todas as extensões instaladas.
list_indexes Liste todos os índices na tabela products.
list_locks Mostra todos os bloqueios ativos no banco de dados.
list_schemas Liste todos os esquemas no banco de dados.
list_sequences Mostra todas as sequências no esquema atual.
list_triggers Liste todos os gatilhos da tabela orders.
list_views Mostre todas as visualizações no esquema sales.
Gerenciamento de recursos
clusters, instâncias, usuários		 create_cluster Crie um cluster do AlloyDB chamado sales-quarterly-db na região us-east1.
get_cluster Receba os detalhes do cluster sales-quarterly-db.
list_clusters Liste todos os meus clusters do AlloyDB.
create_instance Crie uma nova instância de leitura no cluster sales-quarterly-db.
get_instance Mostre as informações da instância sales-quarterly-db-rp.
list_instances Liste todas as instâncias no cluster sales-quarterly-db.
create_user Crie um usuário do banco de dados chamado reporting_user com a senha report_password.
Crie um usuário do banco de dados do IAM para reporting_user@example.com.
get_user Receba as informações do usuário reporting_user.
list_users Liste todos os usuários do banco de dados.
wait_for_operation Qual é o status da operação operation-163562789?
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 da instância principal?
list_top_bloated_tables Liste as cinco tabelas mais inchadas.
list_replication_slots Mostra todos os slots de replicação ativos.
replication_stats Mostra as estatísticas de replicação atuais.
list_invalid_indexes Verifique se há índices inválidos no banco de dados ecommerce.
long_running_transactions Há transações de longa duração?

Extensão de observabilidade do AlloyDB

A extensão alloydb-observability oferece uma interface unificada para gerenciar e monitorar a performance e a integridade do banco de dados diretamente na CLI do Gemini.

Categoria Ferramentas Exemplo de comando em linguagem natural
Observabilidade get_system_metrics Quais são as métricas do sistema, como uso da CPU, da última hora?
get_query_metrics Mostre as métricas de performance da consulta dos últimos 15 minutos.

Você pode usar a extensão da CLI do Gemini para o AlloyDB 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.
  2. Instale a extensão do AlloyDB para a CLI do Gemini no repositório do GitHub usando o seguinte comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/alloydb
  3. Defina as variáveis de ambiente para se conectar à instância do AlloyDB: 
    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"

    Por padrão, a extensão da CLI do Gemini para o AlloyDB usa suas [credenciais padrão do aplicativo (ADC)](/authentication/application-default-credentials) para autenticação. Se você quiser se conectar como um usuário do banco de dados, defina as seguintes variáveis de ambiente opcionais:

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

    Para se conectar usando um endereço IP particular, também é necessário definir a seguinte variável de ambiente:

    export ALLOYDB_POSTGRES_IP_TYPE="private"
  4. Inicie a CLI do Gemini no modo interativo: 
    gemini
    A CLI carrega automaticamente a extensão do AlloyDB para a extensão da CLI do Gemini e as ferramentas dela, que você pode usar para interagir com seu banco de dados.

Gemini Code Assist

Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini. Essa abordagem elimina a necessidade de configurar manualmente um servidor MCP.

  1. Confira se você instalou e configurou a CLI do Gemini e a extensão alloydb.
  2. Configure o Gemini Code Assist para usar a CLI do Gemini.
  3. Comece a interagir com sua instância do AlloyDB usando linguagem natural diretamente no chat do Gemini Code Assist.

Conecte-se com o Antigravity

É possível conectar o AlloyDB ao Antigravity das seguintes maneiras:

  • Como usar a loja do MCP
  • Usar uma configuração personalizada

Observação:não é necessário fazer o download do binário da MCP Toolbox para usar esses métodos.

Loja MCP

O método mais recomendado para se conectar ao AlloyDB no Antigravity é usar o MCP Store integrado.

  1. Abra o Antigravity e o painel do agente do editor.
  2. Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
  3. Localize AlloyDB para PostgreSQL na lista de servidores disponíveis e clique em Instalar.
  4. Siga as instruções na tela para vincular suas contas com segurança (quando aplicável).

Depois de instalar o AlloyDB na loja do MCP, os recursos e as ferramentas do servidor ficam disponíveis automaticamente para o editor.

Configuração personalizada

Para se conectar a um servidor MCP personalizado, siga estas etapas:

  1. Abra o Antigravity e o painel do agente do editor.
  2. Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
  3. Clique em Gerenciar servidores MCP > Ver configuração bruta para abrir o arquivo mcp_config.json.
  4. Adicione e salve a seguinte configuração no arquivo mcp_config.json.
{
  "mcpServers": {
    "alloydb-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--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"
      }
    }
  }
}
Substitua:
  • PROJECT_ID: o ID do projeto Google Cloud .
  • REGION: o nome da sua região do AlloyDB.
  • CLUSTER_NAME: o nome do cluster do AlloyDB.
  • INSTANCE_NAME: o nome da sua instância do AlloyDB.
  • DATABASE_NAME: o nome do banco de dados do AlloyDB.
  • USERNAME: seu nome de usuário do AlloyDB para a variável ALLOYDB_POSTGRES_USER.
  • PASSWORD: sua senha do AlloyDB para a variável ALLOYDB_POSTGRES_PASSWORD.

Conectar-se a outras IDEs usando o MCP Toolbox for Databases

Esta seção descreve como se conectar à instância do AlloyDB de vários agentes usando a MCP Toolbox for Databases. A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu IDE e seu banco de dados, fornecendo um plano de controle para suas ferramentas de IA. Esta seção fornece instruções para se conectar a uma instância do AlloyDB usando um endereço IP público ou privado. Por padrão, a caixa de ferramentas usa um endereço IP público, mas é possível configurar uma conexão por IP particular definindo a variável de ambiente ALLOYDB_POSTGRES_IP_TYPE, conforme mostrado nos exemplos de configuração.

Instalar o MCP Toolbox for Databases

Para conectar seu ambiente de desenvolvimento integrado ao AlloyDB, 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 de CPU. Use a versão v0.15.0 ou mais recente da caixa de ferramentas.

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

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": {
    "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 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": {
    "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. Reinicie o Claude para computador.
  2. A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP.

Cline

  1. Abra a extensão Cline no VS Code e toque 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": {
    "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"
      }
    }
  }
}

Um status ativo verde aparece depois que o servidor se conecta.

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": {
    "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. Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

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

Acessar insights de consultas avançados usando o MCP Toolbox for Databases

Use a MCP Toolbox for Databases para acessar os recursos de observabilidade do AlloyDB e insights de consultas avançados diretamente no seu ambiente de desenvolvimento integrado. Isso permite que os agentes de IA analisem estatísticas de execução de consultas, monitorem eventos de espera e recuperem recomendações de índice para resolver problemas de desempenho do banco de dados.

Funções exigidas

Para receber as permissões necessárias para usar as configurações predefinidas de observabilidade do AlloyDB na caixa de ferramentas do MCP para bancos de dados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto em que você quer usar as ferramentas:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar as configurações predefinidas de observabilidade do AlloyDB na MCP Toolbox for Databases. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para usar as configurações predefinidas de observabilidade do AlloyDB na MCP Toolbox for Databases:

  • Receber métricas de consulta: queryMetrics.fetch
  • Acessar métricas do sistema: systemMetrics.fetch
  • Receba estatísticas avançadas agregadas de consultas: queryStats.fetch
  • Receber estatísticas avançadas de consultas de série temporal: queryTimeSeries.fetch
  • Receba estatísticas avançadas agregadas de eventos de espera: waitEventStats.fetch
  • Receba estatísticas avançadas de eventos de espera de série temporal: waitEventTimeSeries.fetch
  • Receber recomendações de índice: recommendations.query, resourceRecommendations.query
  • Ver métricas do Monitoring: monitoring.timeseries.list

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para configurar seu ambiente de desenvolvimento integrado para usar a configuração pré-criada alloydb-postgres-observability, adicione a seguinte configuração ao arquivo de configuração do MCP do cliente.

Para mais informações, consulte a documentação da configuração predefinida do MCP Toolbox for Databases: AlloyDB para PostgreSQL observability.

{
  "mcpServers": {
    "alloydb-observability": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt", "alloydb-postgres-observability", "--stdio"],
    }
  }
}

Ao se conectar com essa configuração predefinida, seu agente pode invocar as seguintes ferramentas de insights de consultas avançadas do AlloyDB para solucionar problemas de performance:

Conectar usando a extensão do Data Agent Kit

Com a extensão do Google Cloud Data Agent Kit, é possível se conectar e consultar seu banco de dados do AlloyDB diretamente no VS Code ou em outros IDEs baseados no VS Code.

Confira os benefícios de usar o Data Agent Kit:

  • Recursos de descoberta e análise de dados que permitem fazer perguntas sobre seus dados do AlloyDB em linguagem natural
  • A eliminação da troca de contexto entre as ferramentas do AlloyDB e seu ambiente de desenvolvimento
  • Plug-ins que permitem usar CLIs de agentes com seus recursos do Google Cloud

Para mais informações, consulte Visão geral da extensão do Data Agent Kit para VS Code.