Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Usa AlloyDB Omni con MCP Toolbox para la integración de agentes

1. Introducción

Para otorgar a los agentes de IA, como la CLI de Antigravity, acceso seguro y estructurado a tu base de datos, puedes integrar AlloyDB Omni con MCP Toolbox para bases de datos.

AlloyDB Omni es una edición descargable y alojada en contenedores de AlloyDB para PostgreSQL diseñada para ejecutarse en cualquier lugar (de forma local, en estaciones de trabajo de desarrolladores, en el perímetro o en la nube) y, al mismo tiempo, ofrecer rendimiento y compatibilidad con PostgreSQL de nivel empresarial.

MCP Toolbox para bases de datos es un servidor de código abierto de Google que implementa el protocolo de contexto de modelo (MCP) para que sea más fácil, rápido y seguro crear herramientas de IA generativa que interactúen con bases de datos. Se ubica entre el framework de organización de tu agente y tu base de datos, y proporciona las siguientes capacidades:

Desarrollo simplificado: Herramientas de bases de datos prediseñadas o personalizadas que se conectan a tu agente con una configuración mínima y se pueden reutilizar en varios agentes o frameworks.
Mejor rendimiento: Prácticas recomendadas integradas, como la agrupación de conexiones y la administración del ciclo de vida.
Seguridad mejorada: Administración centralizada de credenciales y autenticación para que los agentes no requieran credenciales de base de datos sin procesar.
Observabilidad de extremo a extremo: Métricas y seguimientos listos para usar con compatibilidad integrada con OpenTelemetry.

Al final de este codelab, tendrás un contenedor de AlloyDB Omni en ejecución propagado con datos de comercio electrónico de muestra, un servidor de MCP Toolbox que expone 31 herramientas de consultas de administración y consulta de AlloyDB Omni compiladas previamente, y un agente de la CLI de Antigravity (agy) configurado que puede inspeccionar esquemas, ejecutar consultas en SQL, analizar planes de consultas y diagnosticar el estado de la base de datos con instrucciones en lenguaje natural.

Diagrama de arquitectura que muestra el flujo de trabajo de extremo a extremo desde el agente hasta el cliente de MCP (CLI de Antigravity), la caja de herramientas de MCP y AlloyDB Omni

Requisitos previos

Acceso a un proyecto de Google Cloud y a Cloud Shell desde la consola de Google Cloud o una estación de trabajo de Linux
Docker instalado y en ejecución
El cliente de PostgreSQL psql instalado.
curl y jq instalados para configurar la CLI de Antigravity y la caja de herramientas de MCP

Qué aprenderás

Cómo implementar y ejecutar un contenedor de servidor de base de datos de AlloyDB Omni con Docker.
Cómo crear tablas, datos y un índice de muestra en AlloyDB Omni
Cómo descargar, configurar e iniciar MCP Toolbox para bases de datos con el conjunto de herramientas de alloydb-omni precompilado
Cómo configurar la CLI de Antigravity como un cliente de MCP para conectarse al servidor de MCP Toolbox
Cómo usar instrucciones de lenguaje natural en la CLI de Antigravity para inspeccionar el estado de la base de datos, explorar esquemas, ejecutar consultas en SQL, analizar planes de consultas y realizar diagnósticos de mantenimiento

Requisitos

Un entorno de terminal en funcionamiento con Docker, psql, curl y jq. Puedes usar Google Cloud Shell, que viene con estas herramientas preinstaladas.

2. Configuración y requisitos

Configura el proyecto

Crea un proyecto de Google Cloud

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Inicie Cloud Shell

Aunque puedes ejecutar AlloyDB Omni y MCP Toolbox de forma local en tu laptop, en este codelab puedes usar Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube y que viene preinstalado con Docker, psql, curl y jq.

Ícono para activar Cloud Shell

Abre la consola de Google Cloud y haz clic en Activar Cloud Shell en la barra de herramientas de la parte superior derecha.También puedes abrir Cloud Shell de una de las siguientes maneras:
- Si usas la consola de Google Cloud, presiona G y, luego, S.
- Abre Cloud Shell directamente.

Por lo general, el aprovisionamiento y la conexión al entorno tardan solo unos momentos. Cuando se complete esta operación, verás un resultado similar al siguiente:

Terminal de Google Cloud Shell que muestra que el entorno se conectó

3. Prepara y ejecuta el servidor de la base de datos de AlloyDB Omni

En esta sección, extraerás y ejecutarás el contenedor de Docker de AlloyDB Omni, y lo propagarás con datos de muestra de comercio electrónico para realizar pruebas.

Inicia el servidor de la base de datos de AlloyDB Omni

Define variables de entorno para el host, el puerto, la base de datos, el usuario y una contraseña generada de 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"

Inicia el contenedor de AlloyDB Omni en modo desconectado con Docker:

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

Verifica que el contenedor se esté ejecutando y que puedas conectarte al servidor de AlloyDB Omni con 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;"

Crea datos de muestra para realizar pruebas

Crea tablas de muestra de categories, products, customers y orders, inserta registros de prueba y crea índices para que puedas probar la inspección de esquemas, las consultas en SQL y los planes de ejecución de consultas a través de 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. Inicia el servidor de MCP Toolbox

En esta sección, descargarás el objeto binario de MCP Toolbox, configurarás las definiciones de herramientas de AlloyDB Omni precompiladas y, luego, iniciarás el servidor de MCP Toolbox.

Descarga MCP Toolbox

Crea un directorio para MCP Toolbox y descarga el objeto binario 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

Configura e inicia el servidor de MCP Toolbox

Descarga la configuración de herramientas de alloydb-omni.yaml compilada previamente y, luego, inicia el servidor de MCP Toolbox en el puerto 5000 (con las variables de entorno de ALLOYDB_OMNI_* que exportaste antes):
```
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
```
La configuración alloydb-omni.yaml proporciona 31 herramientas compiladas previamente, incluidas las herramientas clave que se muestran en este codelab:
- execute_sql
- get_query_plan
- database_overview
- list_active_queries
- list_tables, list_indexes, list_views y list_triggers
- list_top_bloated_tables, list_locks, list_autovacuum_configurations y list_invalid_indexes
Para obtener la lista completa de herramientas, consulta alloydb-omni.yaml en GitHub.
Sugerencia: Mantén el servidor de MCP Toolbox en ejecución en esta pestaña de la terminal y abre una nueva (+ en Cloud Shell) para ejecutar los comandos restantes de este codelab.

En una nueva pestaña de la terminal, verifica que el servidor de MCP Toolbox se esté ejecutando y exponga tus herramientas a través del extremo 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. Configura el cliente de MCP (CLI de Antigravity)

En esta sección, instalarás la CLI de Antigravity (agy) y la configurarás para que se conecte a tu servidor de MCP Toolbox.

Instala la CLI de Antigravity

Si aún no lo hiciste, descarga y ejecuta el instalador de la CLI de Antigravity (agy) y verifica la versión:

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

Configura la CLI de Antigravity

Agrega la entrada del servidor de MCP Toolbox al archivo de configuración de MCP de tu cliente (como ~/.gemini/config/mcp_config.json para la CLI de Antigravity, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json o .mcp.json para Claude Code).

Para conectar la CLI de Antigravity al servidor HTTP de MCP Toolbox que se ejecuta en el puerto 5000, ejecuta agy mcp add y verifica la entrada con 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
```
Esto escribe la configuración del servidor de alloydb-omni en ~/.gemini/config/mcp_config.json:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Verifica la configuración

Inicia la CLI de Antigravity:
```
agy
```
Si es la primera vez que inicias agy, sigue los mensajes en pantalla para acceder (con OAuth de Google o un proyecto de Google Cloud) y selecciona Yes, I trust this folder cuando se te pregunte si confías en el directorio actual.

En el mensaje de la CLI de Antigravity, ingresa /mcp para abrir el panel servidores de MCP y verificar que alloydb-omni esté conectado:

/mcp

El resultado es similar al siguiente:

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

Presiona Esc para cerrar el panel servidores de MCP y volver al mensaje de la CLI de Antigravity.

6. Prueba con consultas para AlloyDB Omni

Ahora que la CLI de Antigravity está conectada a tu instancia de AlloyDB Omni a través de MCP Toolbox, puedes interactuar con tu base de datos usando instrucciones en lenguaje natural.

Ejecuta una consulta de descripción general de la base de datos

En el mensaje de la CLI de Antigravity, solicita una descripción general de la base de datos actual:

Give me an overview of the current database.

Cuando se te solicite que permitas llamar a la herramienta, selecciona Sí (o Sí, y permitir siempre en esta conversación). El resultado es similar a este:

> 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)

Ejemplos de pruebas por categoría

Envía las siguientes solicitudes en lenguaje natural a la CLI de Antigravity. El agente asigna automáticamente cada solicitud a la herramienta correspondiente en tu conjunto de herramientas de MCP de AlloyDB Omni:

1. Descripción general y estado de la base de datos

Objetivo de prueba	Instrucción de lenguaje natural	Se invocó la herramienta
Verificación del sistema	`Give me an overview of the current database.`	`database_overview`
Conexiones activas	`What queries are currently running on the database?`	`list_active_queries`
Extensiones instaladas	`What extensions are installed in this database?`	`list_installed_extensions`
Extensiones disponibles	`What extensions are available that I can install?`	`list_available_extensions`

2. Exploración de esquemas y catálogos

Objetivo de prueba	Instrucción de lenguaje natural	Se invocó la herramienta
Enumera tablas	`Show me all the tables in the current database.`	`list_tables`
Inspecciona índices	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Explora las vistas	`What views are available in the public schema?`	`list_views`
Verifica los activadores de tablas	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Consulta y filtrado de datos (`execute_sql`)

Objetivo de prueba	Instrucción de lenguaje natural	Se invocó la herramienta
Consulta de agregación	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Consulta de unión	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Registros que no coinciden	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Rendimiento de las consultas y planes de explicación (`get_query_plan`)

Objetivo de prueba	Instrucción de lenguaje natural	Se invocó la herramienta
Plan de explicación	`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`
Verificación de índices	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Mantenimiento y diagnóstico de bases de datos

Objetivo de prueba	Instrucción de lenguaje natural	Se invocó la herramienta
Sobrecarga de tablas	`List the top five most bloated tables.`	`list_top_bloated_tables`
Contención de bloqueo	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Configuración de autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Índices no válidos	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Limpia

Después de terminar el codelab, limpia el contenedor local y los procesos que iniciaste.

Escribe /quit (o presiona Ctrl+D dos veces) para salir de la CLI de Antigravity.
Cambia a la pestaña de la terminal en la que se ejecuta el servidor de MCP Toolbox y presiona Ctrl+C para detenerlo.
Detén y quita el contenedor de Docker de AlloyDB Omni:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Felicitaciones

¡Felicitaciones por completar el codelab! Implementaste correctamente AlloyDB Omni en un contenedor, configuraste MCP Toolbox para bases de datos con el conjunto de herramientas precompilado de AlloyDB Omni y lo integraste con la CLI de Antigravity para consultar y administrar tu base de datos con lenguaje natural.

Temas abordados

Cómo implementar y verificar un contenedor de AlloyDB Omni con Docker.
Cómo propagar tablas y de índices de muestra para probar los flujos de trabajo de los agentes
Cómo configurar y ejecutar MCP Toolbox para bases de datos con la configuración de herramientas de alloydb-omni precompilada
Cómo conectar la CLI de Antigravity a MCP Toolbox y ejecutar instrucciones de lenguaje natural para el descubrimiento de esquemas, consultas en SQL, análisis de planes de consultas y diagnósticos de bases de datos

Para obtener más información, consulta los siguientes recursos:

9. Encuesta

¿Cómo usarás este instructivo?

Solo lo leeré

Lo leeré y completaré los ejercicios