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 o 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 caixa de ferramentas do MCP para bases de dados. O Toolbox é um servidor MCP de código aberto concebido para associar 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 na nuvem	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 role (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 role (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 projeto que o AlloyDB. Google Cloud

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

Extensão AlloyDB

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

Os exemplos seguintes usam uma base de dados de amostra ecommerce com as seguintes tabelas:

• products: contém informações sobre o 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 sobre a encomenda, incluindo order_id, customer_id e order_date.

Categoria	Ferramentas	Exemplo de comando de linguagem natural
Operações de base de dados	database_overview	Dá-me uma vista geral da base de dados atual.
	list_tables	Mostra-me todas as tabelas na base de dados atual.
	execute_sql	Mostra-me os 10 produtos mais caros na categoria "Portáteis".
	list_active_queries	Que consultas estão a ser executadas na base de dados?
	get_query_plan	Explique o plano de consulta para uma consulta que encontra todos os clientes que não fizeram uma encomenda nos últimos 6 meses.
	list_available_extensions	Quais são as extensões disponíveis que posso instalar?
	list_installed_extensions	Liste todas as extensões instaladas.
	list_indexes	Indicar todos os índices na tabela products.
	list_locks	Mostrar todos os bloqueios ativos na base de dados.
	list_schemas	Liste todos os esquemas na base de dados.
	list_sequences	Mostrar todas as sequências no esquema atual.
	list_triggers	Listar todos os acionadores da tabela orders.
	list_views	Mostra-me todas as vistas no esquema sales.
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	Nota: a ferramenta create_user pode criar dois tipos de utilizadores da base de dados: Utilizadores da base de dados com autenticação incorporada: estes utilizadores são geridos na base de dados e autenticam-se com uma palavra-passe. Utilizadores de IAM: estes utilizadores são geridos no IAM e autenticam-se através das respetivas credenciais de IAM. Quando cria um utilizador da base de dados com autenticação incorporada, tem de fornecer uma palavra-passe. Quando cria um utilizador do IAM, tem de fornecer o principal do IAM. Crie um novo utilizador da base de dados com o nome reporting_user e a palavra-passe report_password. Crie um novo utilizador da base de dados de IAM para [e-mail].
	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?
Manutenção e estado de funcionamento 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 slots de replicação ativos.
	replication_stats	Mostrar as estatísticas de replicação atuais.
	list_invalid_indexes	Verifique se existem índices inválidos na base de dados ecommerce.
	long_running_transactions	Existem transações de longa duração?

Extensão de observabilidade do AlloyDB

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 comandos autónoma
• Integrado no seu IDE com o Gemini Code Assist

CLI do Gemini

1. Instale a Gemini CLI.
2. Instale a extensão AlloyDB para a Gemini CLI a partir do repositório 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 Gemini CLI 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 o Gemini CLI.
3. Comece a interagir com a sua instância do AlloyDB usando linguagem natural diretamente no chat do Gemini Code Assist.

Interaja com o Antigravity

Pode ligar o AlloyDB ao Antigravity das seguintes formas:

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

Nota: não precisa de transferir o ficheiro binário da caixa de ferramentas do MCP para usar estes métodos.

MCP Store

O método mais recomendado para estabelecer ligação ao AlloyDB no Antigravity é usar a MCP Store integrada.

1. Abra o Antigravity e o painel do agente do editor.
2. Clique no ícone "…" na parte superior do painel e selecione Servidores MCP.
3. Localize o AlloyDB para PostgreSQL na lista de servidores disponíveis e clique em Instalar.
4. Siga as instruções no ecrã para associar as suas contas de forma segura (quando aplicável).

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

Configuração personalizada

Para estabelecer ligação a um servidor MCP personalizado, siga estes passos:

1. Abra o Antigravity e o painel do agente do editor.
2. Clique no ícone "…" na parte superior do painel e selecione Servidores MCP.
3. Clique em Gerir servidores de MCP > Ver configuração não processada para abrir o ficheiro mcp_config.json.
4. Adicione e guarde a seguinte configuração no ficheiro 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"
      }
    }
  }
}

Nota: para estabelecer ligação através de um endereço IP privado, adicione a propriedade "ALLOYDB_POSTGRES_IP_TYPE": "private" ao objeto env. Certifique-se de que adiciona uma vírgula à linha anterior para manter o JSON válido.

Substitua o seguinte:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• REGION: o nome da 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 da base de dados do AlloyDB.
• USERNAME: o seu nome de utilizador do AlloyDB para a variável ALLOYDB_POSTGRES_USER.
• PASSWORD: a sua palavra-passe do AlloyDB para a variável ALLOYDB_POSTGRES_PASSWORD.

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 Model Context Protocol (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 o MCP Toolbox for Databases

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. Transformar o ficheiro binário num ficheiro executável.

   chmod +x toolbox
   

3. Valide a instalação.

   ./toolbox --version
   

Configure o cliente

Selecione a ferramenta do 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, clique 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"