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. É possível 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

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 à sua instância do AlloyDB, conclua as etapas a seguir para configurar seu projeto e banco de dados.

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB.

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

2. Crie ou selecione um cluster e a instância principal dele.
3. Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.
4. 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

Observação: a extensão da CLI do Gemini para AlloyDB é baseada no MCP Toolbox for Databases. A caixa de ferramentas do MCP para bancos de dados está atualmente na versão Beta (pré-v1.0) e pode ter mudanças significativas até o primeiro lançamento estável (v1.0).

A CLI do Gemini é um agente de IA de código aberto criado 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 mais recursos do que 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.

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

Categoria	Ferramentas	Exemplo de comando de linguagem natural
Operações de banco de dados	list_tables	Mostre todas as tabelas no banco de dados atual.
	execute_sql	Execute a consulta: SELECT * FROM products WHERE category = 'electronics';
	list_active_queries	Quais consultas estão sendo executadas no banco de dados?
	get_query_plan	Explique o plano de consulta para "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
	list_available_extensions	Quais extensões estão disponíveis para instalação?
	list_installed_extensions	Liste todas as extensões instaladas.
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 de banco de dados chamado reporting_user.
	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.
	list_invalid_indexes	Verifique se há índices inválidos no banco de dados orders.

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

Categoria	Ferramentas	Exemplo de comando de 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 de consulta dos últimos 15 minutos.

Você pode usar a extensão da CLI do Gemini para 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 comando a seguir:

   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"
   

   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 por padrã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 CLI do Gemini e as ferramentas dela, que podem ser usadas 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 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.

Conectar-se a outros ambientes de desenvolvimento integrado usando o MCP Toolbox for Databases

Nesta seção, descrevemos como se conectar à sua instância do AlloyDB de vários agentes usando a Caixa de ferramentas do MCP para bancos de dados. A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu ambiente de desenvolvimento integrado (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 de IP particular definindo a variável de ambiente ALLOYDB_POSTGRES_IP_TYPE, conforme mostrado nos exemplos de configuração.

Instalar a 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 da 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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Reinicie o Claude Desktop.
5. 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.



Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status verde ativo 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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"