Utiliser AlloyDB Omni avec MCP Toolbox pour l'intégration d'agents

1. Introduction

Pour donner aux agents IA (comme la CLI Antigravity) un accès sécurisé et structuré à votre base de données, vous pouvez intégrer AlloyDB Omni à MCP Toolbox for Databases.

AlloyDB Omni est une édition conteneurisée téléchargeable d'AlloyDB pour PostgreSQL conçue pour s'exécuter n'importe où (sur site, sur les postes de travail des développeurs, en périphérie ou dans le cloud) tout en offrant des performances et une compatibilité PostgreSQL de niveau entreprise.

MCP Toolbox for Databases est un serveur Open Source de Google qui implémente le protocole MCP (Model Context Protocol) pour faciliter, accélérer et sécuriser la création d'outils d'IA générative qui interagissent avec des bases de données. Il se situe entre le framework d'orchestration de votre agent et votre base de données, et offre les fonctionnalités suivantes :

  • Développement simplifié : outils de base de données prédéfinis ou personnalisés qui se connectent à votre agent avec une configuration minimale et peuvent être réutilisés sur plusieurs agents ou frameworks.
  • Performances améliorées : bonnes pratiques intégrées telles que le regroupement de connexions et la gestion du cycle de vie.
  • Sécurité renforcée : gestion centralisée des identifiants et de l'authentification pour que les agents n'aient pas besoin d'identifiants de base de données bruts.
  • Observabilité de bout en bout : métriques et traçage prêts à l'emploi avec compatibilité intégrée avec OpenTelemetry.

À la fin de cet atelier de programmation, vous disposerez d'un conteneur AlloyDB Omni en cours d'exécution contenant des exemples de données d'e-commerce, d'un serveur MCP Toolbox exposant 31 outils d'administration et de requête AlloyDB Omni prédéfinis, et d'un agent Antigravity CLI (agy) configuré capable d'inspecter des schémas, d'exécuter des requêtes SQL, d'analyser des plans de requête et de diagnostiquer l'état de la base de données à l'aide d'invites en langage naturel.

Diagramme d'architecture montrant le workflow de bout en bout, de l'agent au client MCP (CLI Antigravity), à MCP Toolbox et à AlloyDB Omni

Prérequis

  • Accès à un projet Google Cloud et à Cloud Shell depuis la console Google Cloud ou un poste de travail Linux.
  • Docker installé et en cours d'exécution.
  • Le client PostgreSQL psql est installé.
  • curl et jq installés pour configurer la CLI Antigravity et MCP Toolbox.

Points abordés

  • Déployer et exécuter un conteneur de serveur de base de données AlloyDB Omni à l'aide de Docker
  • Créer des exemples de tables, de données et d'index dans AlloyDB Omni
  • Télécharger, configurer et démarrer MCP Toolbox for Databases avec l'ensemble d'outils alloydb-omni prédéfini.
  • Comment configurer la CLI Antigravity en tant que client MCP pour se connecter au serveur MCP Toolbox.
  • Comment utiliser des requêtes en langage naturel dans la CLI Antigravity pour inspecter l'état de la base de données, explorer les schémas, exécuter des requêtes SQL, analyser les plans de requête et effectuer des diagnostics de maintenance.

Prérequis

  • Un environnement de terminal fonctionnel avec Docker, psql, curl et jq. Vous pouvez utiliser Google Cloud Shell, sur lequel ces outils sont préinstallés.

2. Préparation

Configuration du projet

Créer un projet Google Cloud

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
  2. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Démarrer Cloud Shell

Bien que vous puissiez exécuter AlloyDB Omni et MCP Toolbox localement sur votre ordinateur portable, dans cet atelier de programmation, vous pouvez utiliser Google Cloud Shell, un environnement de ligne de commande exécuté dans le cloud et préinstallé avec Docker, psql, curl et jq.

Icône d'activation de Cloud Shell

  1. Ouvrez la console Google Cloud et cliquez sur Activer Cloud Shell dans la barre d'outils en haut à droite.Vous pouvez également ouvrir Cloud Shell de l'une des manières suivantes :
    • Si vous utilisez la console Google Cloud, appuyez sur G, puis sur S.
    • Ouvrez directement Cloud Shell.

Le provisionnement et la connexion à l'environnement prennent généralement quelques instants. Une fois l'opération terminée, un résultat semblable à celui-ci s'affiche :

Terminal Google Cloud Shell indiquant que l'environnement est connecté

3. Préparer et exécuter le serveur de base de données AlloyDB Omni

Dans cette section, vous allez extraire et exécuter le conteneur Docker AlloyDB Omni, puis le remplir avec des exemples de données d'e-commerce à des fins de test.

Démarrer le serveur de base de données AlloyDB Omni

  1. Définissez des variables d'environnement pour l'hôte, le port, la base de données, l'utilisateur et un mot de passe généré pour 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"
  2. Démarrez le conteneur AlloyDB Omni en mode détaché à l'aide de Docker :
    docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest
  3. Vérifiez que le conteneur est en cours d'exécution et que vous pouvez vous connecter au serveur AlloyDB Omni à l'aide de 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;"

Créer des exemples de données pour les tests

Créez des exemples de tables categories, products, customers et orders, insérez des enregistrements de test et créez des index pour pouvoir tester l'inspection de schéma, les requêtes SQL et les plans d'exécution de requêtes via 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. Démarrer le serveur MCP Toolbox

Dans cette section, vous allez télécharger le binaire MCP Toolbox, configurer les définitions d'outils AlloyDB Omni prédéfinies et démarrer le serveur MCP Toolbox.

Télécharger MCP Toolbox

  1. Créez un répertoire pour MCP Toolbox et téléchargez le binaire 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

Configurer et démarrer le serveur MCP Toolbox

  1. Téléchargez la configuration d'outils alloydb-omni.yaml prédéfinie et démarrez le serveur MCP Toolbox sur le port 5000 (à l'aide des variables d'environnement ALLOYDB_OMNI_* exportées précédemment) :
    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 configuration alloydb-omni.yaml fournit 31 outils prédéfinis, y compris les outils clés présentés dans cet atelier de programmation :
    • 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
    Pour obtenir la liste complète des outils, consultez alloydb-omni.yaml sur GitHub.
  2. Dans un nouvel onglet de terminal, vérifiez que le serveur MCP Toolbox est en cours d'exécution et expose vos outils via le point de terminaison 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. Configurer le client MCP (CLI Antigravity)

Dans cette section, vous allez installer la CLI Antigravity (agy) et la configurer pour qu'elle se connecte à votre serveur MCP Toolbox.

Installer la CLI Antigravity

  1. Si elle n'est pas déjà installée, téléchargez et exécutez le programme d'installation de la CLI Antigravity (agy), puis vérifiez la version :
    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

Configurer la CLI Antigravity

Ajoutez l'entrée du serveur MCP Toolbox au fichier de configuration MCP de votre client (par exemple, ~/.gemini/config/mcp_config.json pour la CLI Antigravity, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json ou .mcp.json pour Claude Code).

  1. Pour connecter la CLI Antigravity au serveur HTTP MCP Toolbox en cours d'exécution sur le port 5000, exécutez agy mcp add et vérifiez l'entrée avec 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
    Cette commande écrit la configuration du serveur alloydb-omni dans ~/.gemini/config/mcp_config.json :
    {
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

Vérifier la configuration

  1. Démarrez la CLI Antigravity :
    agy
    Si vous lancez agy pour la première fois, suivez les instructions à l'écran pour vous connecter (avec Google OAuth ou un projet Google Cloud), puis sélectionnez Yes, I trust this folder (Oui, je fais confiance à ce dossier) lorsqu'on vous demande si vous faites confiance au répertoire actuel.
  2. Dans l'invite de la CLI Antigravity, saisissez /mcp pour ouvrir le panneau MCP Servers (Serveurs MCP) et vérifier que alloydb-omni est connecté :
    /mcp
    Le résultat ressemble à ce qui suit :
    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
  3. Appuyez sur Esc pour fermer le panneau MCP Servers (Serveurs MCP) et revenir à l'invite de la CLI Antigravity.

6. Tester à l'aide de requêtes pour AlloyDB Omni

Maintenant que la CLI Antigravity est connectée à votre instance AlloyDB Omni via MCP Toolbox, vous pouvez interagir avec votre base de données à l'aide de requêtes en langage naturel.

Exécuter une requête de présentation de la base de données

  1. Dans l'invite de la CLI Antigravity, demandez un aperçu de la base de données actuelle :
    Give me an overview of the current database.
    Lorsque vous êtes invité à autoriser l'appel de l'outil, sélectionnez Oui (ou Oui, et toujours autoriser dans cette conversation). Le résultat ressemble à ce qui suit :
    > 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)

Exemples de tests par catégorie

Envoyez les requêtes en langage naturel suivantes à la CLI Antigravity. L'agent mappe automatiquement chaque requête à l'outil correspondant dans votre ensemble d'outils MCP AlloyDB Omni :

1. Présentation et état de la base de données

Objectif de test

Prompt en langage naturel

Outil appelé

Vérification du système

Give me an overview of the current database.

database_overview

Connexions actives

What queries are currently running on the database?

list_active_queries

Extensions installées

What extensions are installed in this database?

list_installed_extensions

Extensions disponibles

What extensions are available that I can install?

list_available_extensions

2. Exploration du schéma et du catalogue

Objectif de test

Prompt en langage naturel

Outil appelé

Répertorier les tables

Show me all the tables in the current database.

list_tables

Inspecter les index

List all indexes in the database and which tables they belong to.

list_indexes

Explorer les vues

What views are available in the public schema?

list_views

Vérifier les déclencheurs de table

Show me the triggers defined on the orders table.

list_triggers

3. Interrogation et filtrage des données (execute_sql)

Objectif de test

Prompt en langage naturel

Outil appelé

Requête d'agrégation

Show me the 3 most expensive products in the 'Laptops' category.

execute_sql

Requête de jointure

Find all customers who have placed an order in the last 6 months.

execute_sql

Enregistrements sans correspondance

Which customers haven't placed any orders yet?

execute_sql

4. Performances des requêtes et plans d'explication (get_query_plan)

Objectif de test

Prompt en langage naturel

Outil appelé

Expliquer le plan

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

Validation de l'index

Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.

get_query_plan

5. Maintenance et diagnostics de la base de données

Objectif de test

Prompt en langage naturel

Outil appelé

Gonflement de table

List the top five most bloated tables.

list_top_bloated_tables

Conflits de verrouillage

Show me if there are any active locks or blocked transactions.

list_locks

Paramètres d'autovacuum

Show me the current autovacuum configuration.

list_autovacuum_configurations

Index non valides

Check for any invalid indexes in the database.

list_invalid_indexes

7. Effectuer un nettoyage

Une fois l'atelier de programmation terminé, nettoyez le conteneur local et les processus que vous avez lancés.

  1. Quittez la CLI Antigravity en saisissant /quit (ou en appuyant deux fois sur Ctrl+D).
  2. Accédez à l'onglet du terminal exécutant le serveur MCP Toolbox et appuyez sur Ctrl+C pour l'arrêter.
  3. Arrêtez et supprimez le conteneur Docker AlloyDB Omni :
    docker stop alloydbomni
docker rm alloydbomni

8. Félicitations

Félicitations, vous avez terminé cet atelier de programmation ! Vous avez déployé AlloyDB Omni dans un conteneur, configuré MCP Toolbox for Databases avec l'ensemble d'outils AlloyDB Omni prédéfini et l'avez intégré à la CLI Antigravity pour interroger et gérer votre base de données en langage naturel.

Points abordés

  • Déployer et vérifier un conteneur AlloyDB Omni à l'aide de Docker
  • Comment remplir des exemples de tables et d'index pour tester les workflows d'agent.
  • Configurer et exécuter MCP Toolbox for Databases avec la configuration d'outils alloydb-omni prédéfinie.
  • Comment connecter la CLI Antigravity à MCP Toolbox et exécuter des requêtes en langage naturel pour la découverte de schémas, l'interrogation SQL, l'analyse de plans de requête et les diagnostics de base de données.

Pour en savoir plus, consultez les ressources suivantes :

9. Enquête

Comment allez-vous utiliser ce tutoriel ?

Je vais le lire uniquement Je vais le lire et effectuer les exercices