Use o AlloyDB for PostgreSQL com o MCP, a Gemini CLI e outros agentes

Este documento descreve como ligar a sua instância do AlloyDB a vários agentes que suportam o protocolo Model Context Protocol (MCP).

Recomendamos que use a extensão AlloyDB dedicada para a Gemini CLI. A CLI Gemini integra o servidor MCP subjacente diretamente na extensão, pelo que não tem de fazer uma configuração de servidor separada. Pode configurar o Gemini Code Assist para usar a Gemini CLI, o que oferece vantagens de configuração semelhantes no seu IDE.

Em alternativa, outros IDEs e agentes que suportem o MCP podem estabelecer ligação através da MCP Toolbox for Databases. O Toolbox é um servidor MCP de código aberto concebido para ligar agentes de IA aos seus dados. Processa tarefas como a autenticação e a partilha de ligações, o que lhe permite interagir com os seus dados com linguagem natural diretamente a partir do IDE.

Antes de começar

Para se ligar à sua instância do AlloyDB e usar as ferramentas disponíveis, tem de ter uma das seguintes funções de gestão de identidade e acesso (IAM) ou uma função personalizada com autorizações equivalentes:

Tarefa	Nome da função	Função de gestão de identidade e de acesso (IAM) necessária
Use ferramentas só de leitura para listar e obter recursos do AlloyDB	Leitor do AlloyDB	roles/alloydb.viewer
Associe-se a uma instância e execute consultas	Cliente do AlloyDB no Cloud	roles/alloydb.client
	Consumidor da utilização do serviço	roles/serviceusage.serviceUsageConsumer
Realizar tarefas administrativas (como criar ou gerir clusters, instâncias e utilizadores)	Administrador do AlloyDB	roles/alloydb.admin
Use a extensão de observabilidade	Visualizador de monitorização	roles/monitoring.viewer

Antes de se poder ligar à sua instância do AlloyDB, conclua os passos seguintes para configurar o projeto e a base 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 Google Cloud necessárias para criar e estabelecer ligação ao AlloyDB.

   Ative as APIs

   1. No passo Confirmar projeto, clique em Seguinte para confirmar o nome do projeto ao qual vai fazer alterações.

   2. No passo Ativar APIs, clique em Ativar para ativar o seguinte:

      • API AlloyDB
      • API Compute Engine
      • Cloud Resource Manager API
      • API de rede de serviços

      A API Service Networking é necessária se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que resida no mesmo Google Cloud projeto que o AlloyDB.

      A API Compute Engine e a API Cloud Resource Manager são necessárias se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que reside num projeto Google Cloud diferente.

2. Crie ou selecione um cluster e a respetiva instância principal.
3. Configure as credenciais padrão da aplicação (ADC) para o seu ambiente.
4. Crie ou reutilize um utilizador da base de dados. Tenha o nome de utilizador e a palavra-passe prontos para introduzir.

Use as extensões da Gemini CLI para o AlloyDB

Nota: a extensão da CLI do Gemini para o AlloyDB baseia-se no MCP Toolbox for Databases. Atualmente, a caixa de ferramentas do MCP para bases de dados está na versão beta (pré-v1.0) e pode sofrer alterações significativas até ao primeiro lançamento estável (v1.0).

O Gemini CLI é um agente de IA de código aberto concebido para ajudar nos fluxos de trabalho de desenvolvimento, auxiliando na programação, na depuração, na exploração de dados e na criação de conteúdo. A sua missão é fornecer uma interface de agente para interagir com os serviços do Data Cloud e bases de dados de código aberto populares.

A integração com a CLI do Gemini é feita através de extensões dedicadas que oferecem capacidades adicionais em comparação com uma ligação padrão da caixa de ferramentas do MCP. As secções seguintes 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 a instalação, a configuração e exemplos de utilização. Para mais informações, consulte o artigo Extensão da CLI Gemini – AlloyDB para PostgreSQL.

A extensão alloydb inclui ferramentas para consultar a base de dados, gerir recursos do AlloyDB e monitorizar o estado da base de dados.

Categoria	Ferramentas	Exemplo de comando de linguagem natural
Operações de base de dados	list_tables	Mostra-me todas as tabelas na base de dados atual.
	execute_sql	Execute a consulta: SELECT * FROM products WHERE category = 'electronics';
	list_active_queries	Que consultas estão a ser executadas na base de dados?
	get_query_plan	Explica o plano de consulta para "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
	list_available_extensions	Quais são as extensões disponíveis que posso instalar?
	list_installed_extensions	Liste todas as extensões instaladas.
Gestão de recursos clusters, instâncias, utilizadores	create_cluster	Crie um cluster do AlloyDB denominado sales-quarterly-db na região us-east1.
	get_cluster	Obtenha os detalhes do cluster sales-quarterly-db.
	list_clusters	Lista todos os meus clusters do AlloyDB.
	create_instance	Crie uma nova instância de leitura no cluster sales-quarterly-db.
	get_instance	Mostra-me as informações da instância sales-quarterly-db-rp.
	list_instances	Liste todas as instâncias no cluster sales-quarterly-db.
	create_user	Cria um novo utilizador da base de dados com o nome reporting_user.
	get_user	Obtenha as informações do utilizador reporting_user.
	list_users	Liste todos os utilizadores da base de dados.
	wait_for_operation	Qual é o estado da operação operation-163562789?
Estado de funcionamento e manutenção da base de dados	list_autovacuum_configurations	Mostra-me a configuração atual do autovacuum.
	list_memory_configurations	Quais são as configurações de memória atuais para a instância principal?
	list_top_bloated_tables	Apresentar as cinco tabelas mais sobrecarregadas.
	list_replication_slots	Apresenta todos os espaços de replicação ativos.
	list_invalid_indexes	Verifique se existem índices inválidos na base de dados orders.

A extensão alloydb-observability oferece uma interface unificada para gerir e monitorizar o desempenho e o estado da base de dados diretamente a partir da Gemini CLI.

Categoria	Ferramentas	Exemplo de comando de linguagem natural
Observabilidade	get_system_metrics	Quais são as métricas do sistema, como a utilização da CPU, para a última hora?
	get_query_metrics	Mostra-me as métricas de desempenho das consultas dos últimos 15 minutos.

Pode usar a extensão Gemini CLI para o AlloyDB de duas formas:

• Uma ferramenta de linhas de comando autónoma
• Integrado no seu IDE com o Gemini Code Assist

CLI do Gemini

1. Instale a CLI do Gemini.
2. Instale a extensão AlloyDB para a Gemini CLI a partir do repositório do GitHub com o seguinte comando:

   gemini extensions install https://github.com/gemini-cli-extensions/alloydb
   

3. Defina variáveis de ambiente para se ligar à sua 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 Gemini CLI para o AlloyDB usa as suas [Credenciais padrão da aplicação (ADC)](/authentication/application-default-credentials) para autenticação por predefinição. Se quiser estabelecer ligação como utilizador da base 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 estabelecer ligação através de um endereço IP privado, também tem de 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 Gemini CLI e as respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Gemini Code Assist

Recomendamos que configure o Gemini Code Assist para usar o Gemini CLI. Esta abordagem elimina a necessidade de configurar manualmente um servidor MCP.

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

Estabeleça ligação a outros IDEs através da caixa de ferramentas MCP para bases de dados

Esta secção descreve como estabelecer ligação à sua instância do AlloyDB a partir de vários agentes através da MCP Toolbox for Databases. A caixa de ferramentas funciona como um servidor de protocolo de contexto do modelo (MCP) de código aberto que se encontra entre o seu IDE e a sua base de dados, fornecendo um plano de controlo para as suas ferramentas de IA. Esta secção fornece instruções para estabelecer ligação a uma instância do AlloyDB através de um endereço IP público ou privado. Por predefinição, a caixa de ferramentas usa um endereço IP público, mas pode configurar uma ligação IP privada definindo a variável de ambiente ALLOYDB_POSTGRES_IP_TYPE, conforme mostrado nos exemplos de configuração.

Instale a caixa de ferramentas do MCP para bases de dados

Para associar o seu IDE ao AlloyDB, tem de instalar o MCP Toolbox for Databases, um servidor de código aberto que associa os agentes de IA aos seus dados.

1. Transfira a versão mais recente da caixa de ferramentas como um ficheiro binário. Selecione o binário correspondente ao seu sistema operativo (SO) e arquitetura da CPU. Tem de usar a versão v0.15.0 ou posterior 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. Tornar o ficheiro binário executável.

   chmod +x toolbox
   

3. Valide a instalação.

   ./toolbox --version
   

Configure o cliente

Selecione a ferramenta de agente a partir das seguintes opções:

Código do Claude

1. Instale o Claude Code.
2. Crie o ficheiro .mcp.json na raiz do projeto, se não existir.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




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

Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Claude para computador

1. Abra o Claude Desktop e navegue para Definições.
2. No separador Programador, clique em Editar configuração para abrir o ficheiro de configuração.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




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

Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Reinicie o Claude Desktop.
5. O novo ecrã de chat apresenta 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 ficheiro de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




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


É apresentado um estado ativo verde depois de o servidor se ligar com êxito.



Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Cursor

1. Crie o diretório .cursor na raiz do projeto, se não existir.
2. Crie o ficheiro .cursor/mcp.json, se não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

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

Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Abra o Cursor e navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.

Visual Studio Code (Copilot)

1. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se não existir.
2. Crie o ficheiro .vscode/mcp.json, se não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

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

Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Windsurf

1. Abra o Windsurf e navegue para o assistente Cascade.
2. Clique no ícone do MCP e, de seguida, em Configurar para abrir o ficheiro de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

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

Nota: para estabelecer ligação através de um endereço IP privado, adicione a seguinte linha ao objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"