O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o AlloyDB Omni com o MCP Toolbox para integração de agentes

1. Introdução

Para dar aos agentes de IA, como a CLI do Antigravity, acesso seguro e estruturado ao seu banco de dados, integre o AlloyDB Omni ao MCP Toolbox for Databases.

O AlloyDB Omni é uma edição em contêiner para download do AlloyDB para PostgreSQL projetada para ser executada em qualquer lugar (no local, em estações de trabalho de desenvolvedores, na borda ou na nuvem) e oferecer desempenho e compatibilidade com o PostgreSQL de nível empresarial.

O MCP Toolbox for Databases é um servidor de código aberto do Google que implementa o Protocolo de Contexto de Modelo (MCP) para facilitar, acelerar e proteger a criação de ferramentas de IA generativa que interagem com bancos de dados. Ele fica entre o framework de orquestração do agente e o banco de dados, oferecendo os seguintes recursos:

Desenvolvimento simplificado: ferramentas de banco de dados pré-criadas ou personalizadas que se conectam ao agente com configuração mínima e podem ser reutilizadas em vários agentes ou frameworks.
Melhor desempenho: práticas recomendadas integradas, como pooling de conexões e gerenciamento do ciclo de vida.
Segurança aprimorada: gerenciamento centralizado de credenciais e autenticação para que os agentes não precisem de credenciais de banco de dados brutas.
Observabilidade de ponta a ponta: métricas e rastreamento prontos para uso com suporte integrado ao OpenTelemetry.

Ao final deste codelab, você terá um contêiner do AlloyDB Omni em execução preenchido com dados de e-commerce de amostra, um servidor do MCP Toolbox que expõe 31 ferramentas pré-criadas de administração e consulta do AlloyDB Omni e um agente da CLI do Antigravity (agy) configurado capaz de inspecionar esquemas, executar consultas SQL, analisar planos de consulta e diagnosticar a integridade do banco de dados usando comandos de linguagem natural.

Diagrama de arquitetura que mostra o fluxo de trabalho de ponta a ponta do agente para o cliente MCP (CLI do Antigravity), para o MCP Toolbox e para o AlloyDB Omni

Pré-requisitos

Acesso a um projeto na nuvem do Google Cloud e ao Cloud Shell no console do Google Cloud ou em uma estação de trabalho Linux.
Docker instalado e em execução.
O cliente PostgreSQL psql instalado.
curl e jq instalados para configurar a CLI do Antigravity e a MCP Toolbox.

O que você vai aprender

Como implantar e executar um contêiner de servidor de banco de dados do AlloyDB Omni usando o Docker.
Como criar tabelas, dados e índices de amostra no AlloyDB Omni.
Como baixar, configurar e iniciar o MCP Toolbox for Databases com o conjunto de ferramentas pré-criado alloydb-omni.
Como configurar a CLI do Antigravity como um cliente MCP para se conectar ao servidor do MCP Toolbox.
Como usar comandos de linguagem natural na CLI do Antigravity para inspecionar a integridade do banco de dados, analisar esquemas, executar consultas SQL, analisar planos de consulta e realizar diagnósticos de manutenção.

O que é necessário

Um ambiente de terminal em funcionamento com Docker, psql, curl e jq. Use o Google Cloud Shell, que já vem com essas ferramentas pré-instaladas.

2. Configuração e requisitos

Configurar o projeto

Criar um projeto do Google Cloud

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
Verifique se o faturamento está ativado para o projeto do Google Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

Embora seja possível executar o AlloyDB Omni e o MCP Toolbox localmente no seu laptop, neste codelab você pode usar o Google Cloud Shell, um ambiente de linha de comando executado na nuvem que vem pré-instalado com o Docker, psql, curl e jq.

Ícone para ativar o Cloud Shell

Abra o console do Google Cloud e clique em Ativar o Cloud Shell na barra de ferramentas no canto superior direito.Também é possível abrir o Cloud Shell de uma das seguintes maneiras:
- Se você estiver usando o console do Google Cloud, pressione G e S.
- Abra o Cloud Shell diretamente.

O provisionamento e a conexão do ambiente podem demorar um pouco. Quando essa operação for concluída, você verá algo semelhante ao seguinte:

Terminal do Google Cloud Shell mostrando que o ambiente foi conectado

3. Preparar e executar o servidor de banco de dados do AlloyDB Omni

Nesta seção, você vai extrair e executar o contêiner do Docker do AlloyDB Omni e preenchê-lo com dados de e-commerce de amostra para testes.

Iniciar o servidor de banco de dados do AlloyDB Omni

Defina variáveis de ambiente para o host, a porta, o banco de dados, o usuário e uma senha gerada do AlloyDB Omni:

export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"

Inicie o contêiner do AlloyDB Omni no modo separado usando o Docker:

docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest

Verifique se o contêiner está em execução e se é possível se conectar ao servidor do AlloyDB Omni usando psql:

docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

Criar dados de amostra para teste

Crie tabelas de amostra categories, products, customers e orders, insira registros de teste e crie índices para testar a inspeção de esquema, as consultas SQL e os planos de execução de consulta usando o MCP Toolbox:

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. Inicie o servidor do MCP Toolbox

Nesta seção, você vai fazer o download do binário do MCP Toolbox, configurar as definições de ferramentas pré-criadas do AlloyDB Omni e iniciar o servidor do MCP Toolbox.

Baixar o MCP Toolbox

Crie um diretório para o MCP Toolbox e faça o download do binário toolbox:

mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

Configurar e iniciar o servidor do MCP Toolbox

Baixe a configuração de ferramentas alloydb-omni.yaml pré-criada e inicie o servidor do MCP Toolbox na porta 5000 (usando as variáveis de ambiente ALLOYDB_OMNI_* exportadas anteriormente):
```
curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
```
A configuração alloydb-omni.yaml oferece 31 ferramentas pré-criadas, incluindo as principais demonstradas neste codelab:
- execute_sql
- get_query_plan
- database_overview
- list_active_queries
- list_tables, list_indexes, list_views, list_triggers
- list_top_bloated_tables, list_locks, list_autovacuum_configurations, list_invalid_indexes
Para ver a lista completa de ferramentas, consulte alloydb-omni.yaml no GitHub.
Dica: mantenha o servidor da MCP Toolbox em execução nessa guia do terminal e abra uma nova guia (+ no Cloud Shell) para executar os comandos restantes neste codelab.

Em uma nova guia do terminal, verifique se o servidor do MCP Toolbox está em execução e expõe suas ferramentas pelo endpoint JSON-RPC /mcp:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. Configurar o cliente MCP (CLI do Antigravity)

Nesta seção, você vai instalar a CLI do Antigravity (agy) e configurá-la para se conectar ao servidor do MCP Toolbox.

Instalar a CLI do Antigravity

Se ainda não estiver instalado, faça o download e execute o instalador da CLI do Antigravity (agy) e verifique a versão:

curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

Configurar a CLI do Antigravity

Adicione a entrada do servidor do MCP Toolbox ao arquivo de configuração do MCP do cliente (como ~/.gemini/config/mcp_config.json para a CLI do Antigravity, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json ou .mcp.json para o Claude Code).

Para conectar a CLI do Antigravity ao servidor HTTP do MCP Toolbox em execução na porta 5000, execute agy mcp add e verifique a entrada com agy mcp list:

export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list

Isso grava a configuração do servidor alloydb-omni em ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

Confirmar configuração

Inicie a CLI do Antigravity:
```
agy
```
Se esta for a primeira vez que você inicia o agy, siga as mensagens na tela para fazer login (com o OAuth do Google ou um projeto na nuvem do Google Cloud) e selecione Sim, confio nesta pasta quando for perguntado se você confia no diretório atual.

No prompt da CLI do Antigravity, digite /mcp para abrir o painel Servidores MCP e verifique se alloydb-omni está conectado:

/mcp

O resultado será assim:

MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions

Pressione Esc para fechar o painel Servidores MCP e voltar ao prompt da CLI do Antigravity.

6. Testar usando consultas para o AlloyDB Omni

Agora que a CLI do Antigravity está conectada à sua instância do AlloyDB Omni pelo MCP Toolbox, você pode interagir com seu banco de dados usando comandos em linguagem natural.

Executar uma consulta de visão geral do banco de dados

No prompt da CLI do Antigravity, peça uma visão geral do banco de dados atual:

Give me an overview of the current database.

Quando for solicitado que você permita o uso da ferramenta, selecione Sim (ou Sim, e sempre permitir nesta conversa). O resultado será assim:

> Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

Exemplos de teste por categoria

Envie os seguintes comandos em linguagem natural para a CLI do Antigravity. O agente mapeia automaticamente cada solicitação para a ferramenta correspondente no conjunto de ferramentas do MCP do AlloyDB Omni:

1. Visão geral e integridade do banco de dados

Meta do teste	Comando de linguagem natural	Ferramenta invocada
Verificação do sistema	`Give me an overview of the current database.`	`database_overview`
Conexões ativas	`What queries are currently running on the database?`	`list_active_queries`
Extensões instaladas	`What extensions are installed in this database?`	`list_installed_extensions`
Extensões disponíveis	`What extensions are available that I can install?`	`list_available_extensions`

2. Análise de esquemas e catálogos

Meta do teste	Comando de linguagem natural	Ferramenta invocada
Listar tabelas	`Show me all the tables in the current database.`	`list_tables`
Inspecionar índices	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Analisar visualizações	`What views are available in the public schema?`	`list_views`
Verificar gatilhos de tabela	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Consulta e filtragem de dados (`execute_sql`)

Meta do teste	Comando de linguagem natural	Ferramenta invocada
Consulta agregada	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Consulta de mesclagem	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Registros sem correspondência	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Performance de consultas e planos de explicação (`get_query_plan`)

Meta do teste	Comando de linguagem natural	Ferramenta invocada
Explicar plano	`Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.`	`get_query_plan`
Verificação de índice	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Manutenção e diagnóstico de bancos de dados

Meta do teste	Comando de linguagem natural	Ferramenta invocada
Inchaço de tabela	`List the top five most bloated tables.`	`list_top_bloated_tables`
Contenção de bloqueio	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Configurações de autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Índices inválidos	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Limpar

Depois de concluir o codelab, limpe o contêiner local e os processos que você iniciou.

Para sair da CLI do Antigravity, digite /quit ou pressione Ctrl+D duas vezes.
Mude para a guia do terminal que está executando o servidor do MCP Toolbox e pressione Ctrl+C para interrompê-lo.
Interrompa e remova o contêiner do Docker do AlloyDB Omni:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Parabéns

Parabéns por concluir o codelab. Você implantou o AlloyDB Omni em um contêiner, configurou o MCP Toolbox for Databases com o conjunto de ferramentas pré-criado do AlloyDB Omni e o integrou à CLI do Antigravity para consultar e gerenciar seu banco de dados usando linguagem natural.

Conteúdo abordado

Como implantar e verificar um contêiner do AlloyDB Omni usando o Docker.
Como preencher tabelas e índices de amostra para testar Agentic Workflows.
Como configurar e executar o MCP Toolbox for Databases com a configuração de ferramentas alloydb-omni pré-criada.
Como conectar a CLI do Antigravity ao MCP Toolbox e executar comandos em linguagem natural para descoberta de esquemas, consultas SQL, análise de planos de consulta e diagnósticos de banco de dados.

Para saber mais, acesse os recursos a seguir:

9. Pesquisa

Como você usará este tutorial?

Apenas leitura

Leitura e exercícios