Installer et configurer la boîte à outils MCP pour les bases de données pour vos applications d'IA générative et agents sur AlloyDB

À propos de cet atelier de programmation

Dernière mise à jour : avr. 28, 2025

Rédigé par Author: Abirami Sukumaran Anubhav Dhawan

1. Présentation

MCP Toolbox for Databases est un serveur Open Source de Google qui facilite la création d'outils d'IA générative permettant d'interagir avec les bases de données. Il vous permet de développer des outils plus facilement, plus rapidement et de manière plus sécurisée en gérant les complexités telles que le pool de connexions, l'authentification, etc. Il vous aide à créer des outils d'IA générative qui permettent à vos agents d'accéder aux données de votre base de données. Toolbox fournit les éléments suivants:

Développement simplifié:intégrez des outils à votre agent dans moins de 10 lignes de code, réutilisez des outils dans plusieurs agents ou frameworks, et déployez plus facilement de nouvelles versions d'outils.

Performances améliorées:bonnes pratiques telles que le regroupement de connexions, l'authentification, etc.

Sécurité renforcée:l'authentification intégrée offre un accès plus sécurisé à vos données.

Observabilité de bout en bout:métriques et traçage prêts à l'emploi, avec prise en charge intégrée d'OpenTelemetry.

La boîte à outils se trouve entre le framework d'orchestration de votre application et votre base de données. Elle fournit un plan de contrôle permettant de modifier, de distribuer ou d'invoquer des outils. Il simplifie la gestion de vos outils en vous fournissant un emplacement centralisé pour les stocker et les mettre à jour. Vous pouvez ainsi les partager entre les agents et les applications, et les mettre à jour sans avoir à redéployer votre application.

Ce que vous allez faire

Dans cet atelier, vous allez créer une application qui utilise un outil pour exécuter une requête de base de données simple (AlloyDB) pouvant être appelée depuis votre agent ou l'application d'IA générative. Pour cela, vous allez

Installer MCP Toolbox pour les bases de données
Configurer l'outil (conçu pour effectuer une tâche dans AlloyDB) sur le serveur de la boîte à outils
Déployer la boîte à outils MCP pour les bases de données sur Cloud Run
Tester l'outil avec son point de terminaison Cloud Run déployé
Créer la fonction Cloud Run pour appeler la boîte à outils

Conditions requises

Un navigateur tel que Chrome ou Firefox
Un projet Google Cloud avec la facturation activée (procédure de la section suivante)

2. Avant de commencer

Créer un projet

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.
Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.

Image du bouton Activer Cloud Shell

Une fois connecté à Cloud Shell, vérifiez si vous êtes déjà authentifié et si le projet est défini sur le bon ID de projet à l'aide de la commande suivante:

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Activez les API requises en exécutant les commandes suivantes une par une dans votre terminal Cloud Shell:

Vous pouvez également exécuter les commandes ci-dessous à l'aide d'une seule commande. Toutefois, si vous utilisez un compte d'essai, vous risquez de rencontrer des problèmes de quota en essayant d'activer ces éléments de manière groupée. C'est pourquoi les commandes sont uniques par ligne.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

L'alternative à la commande gcloud consiste à utiliser la console, en recherchant chaque produit ou en utilisant ce lien.

Si une API est manquante, vous pouvez toujours l'activer au cours de l'implémentation.

Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.

3. Configuration de la base de données

Dans cet atelier, nous allons utiliser AlloyDB comme base de données pour stocker les données de commerce de détail. Il utilise des clusters pour stocker toutes les ressources, telles que les bases de données et les journaux. Chaque cluster dispose d'une instance principale qui fournit un point d'accès aux données. Les tableaux contiendront les données réelles.

Créons un cluster, une instance et une table AlloyDB dans lesquels l'ensemble de données d'e-commerce sera chargé.

Créer un cluster et une instance

Accédez à la page AlloyDB dans la console Cloud.

Pour trouver facilement la plupart des pages dans la console Cloud, utilisez la barre de recherche de la console.

Sélectionnez CRÉER UN CLUSTER sur cette page:

Un écran semblable à celui présenté ci-dessous s'affiche. Créez un cluster et une instance avec les valeurs suivantes (assurez-vous qu'elles correspondent au cas où vous cloneriez le code d'application à partir du dépôt):

ID du cluster : "vector-cluster"
mot de passe : "alloydb"
Compatible avec PostgreSQL 15
Région : "us-central1"
Mise en réseau : "default"

Lorsque vous sélectionnez le réseau par défaut, un écran semblable à celui présenté ci-dessous s'affiche. Sélectionnez CONFIGURER LA CONNEXION.
Ensuite, sélectionnez "Utiliser une plage d'adresses IP automatiquement allouée", puis cliquez sur "Continuer". Après avoir vérifié les informations, sélectionnez CRÉER UNE CONNEXION.
Une fois votre réseau configuré, vous pouvez continuer à créer votre cluster. Cliquez sur CRÉER UN CLUSTER pour terminer la configuration du cluster comme indiqué ci-dessous:

Veillez à remplacer l'ID d'instance par "

vector-instance"

Notez que la création du cluster prend environ 10 minutes. Une fois l'opération réussie, un écran présentant le cluster que vous venez de créer doit s'afficher.

4. Ingestion de données

Il est maintenant temps d'ajouter un tableau avec les données sur le magasin. Accédez à AlloyDB, sélectionnez le cluster principal, puis AlloyDB Studio:

Vous devrez peut-être attendre la fin de la création de votre instance. Une fois l'opération terminée, connectez-vous à AlloyDB à l'aide des identifiants que vous avez créés lors de la création du cluster. Utilisez les données suivantes pour l'authentification auprès de PostgreSQL:

Nom d'utilisateur : "postgres"
Base de données : "postgres"
Mot de passe : "alloydb"

Une fois que vous vous êtes authentifié dans AlloyDB Studio, vous pouvez saisir des commandes SQL dans l'éditeur. Vous pouvez ajouter plusieurs fenêtres Editor à l'aide du signe plus à droite de la dernière fenêtre.

Vous pouvez saisir des commandes pour AlloyDB dans les fenêtres de l'éditeur, à l'aide des options "Exécuter", "Formater" et "Effacer" si nécessaire.

Activer les extensions

Pour créer cette application, nous utiliserons les extensions pgvector et google_ml_integration. L'extension pgvector vous permet de stocker et de rechercher des représentations vectorielles continues. L'extension google_ml_integration fournit des fonctions permettant d'accéder aux points de terminaison de prédiction Vertex AI afin d'obtenir des prédictions en SQL. Activez ces extensions en exécutant les LDD suivants:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Si vous souhaitez vérifier les extensions qui ont été activées sur votre base de données, exécutez cette commande SQL:

select extname, extversion from pg_extension;

Créer une table

Créez une table à l'aide de l'instruction LDD ci-dessous:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Si la commande ci-dessus réussit, vous devriez pouvoir afficher la table dans la base de données.

Ingérer des données

Pour cet atelier, ce fichier SQL contient des données de test d'environ 72 enregistrements. Il contient les champs id, name, description, quantity, price, image_url. Les autres champs seront remplis plus tard dans l'atelier.

Copiez les lignes/instructions d'insertion à partir de là, collez ces lignes dans un onglet d'éditeur vierge et sélectionnez EXÉCUTER.

Pour voir le contenu de la table, développez la section Explorateur jusqu'à ce que vous voyiez la table nommée "vêtements". Sélectionnez le trois-points (⋮) pour afficher l'option permettant d'interroger la table. Une instruction SELECT s'ouvre dans un nouvel onglet de l'éditeur.

Accorder l'autorisation

Exécutez l'instruction ci-dessous pour accorder des droits d'exécution sur la fonction embedding à l'utilisateur postgres:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Attribuer un ROLE d'utilisateur Vertex AI au compte de service AlloyDB

Accédez au terminal Cloud Shell et exécutez la commande suivante:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. Créer des représentations vectorielles continues pour le contexte

Il est beaucoup plus facile pour les ordinateurs de traiter des nombres que du texte. Un système de représentation vectorielle continue convertit du texte en une série de nombres à virgule flottante, appelés représentations vectorielles continues, qui doivent représenter le texte, quelle que soit sa formulation, sa langue, etc.

Par exemple, un lieu en bord de mer peut être désigné par "sur l'eau", "en bord de plage", "marcher de votre chambre à l'océan", "sur la mer", "на Береfec£ океана" etc. Ces termes sont tous différents, mais leur signification sémantique ou la terminologie du machine learning doivent être très proches les unes des autres.

Maintenant que les données et le contexte sont prêts, nous allons exécuter le code SQL pour ajouter les représentations vectorielles continues de la description du produit à la table du champ embedding. Vous pouvez utiliser de nombreux modèles de représentation vectorielle continue. Nous utilisons text-embedding-005 de Vertex AI. Veillez à utiliser le même modèle de représentation vectorielle continue dans tout le projet !

Remarque: Si vous utilisez un ancien projet Google Cloud, vous devrez peut-être continuer à utiliser d'anciennes versions du modèle de représentation vectorielle continue de texte, comme textembedding-gecko.

Revenez à l'onglet AlloyDB Studio et saisissez le LMD suivant:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Examinez à nouveau la table toys pour voir des représentations vectorielles continues. N'oubliez pas d'exécuter à nouveau l'instruction SELECT pour voir les modifications.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Cela devrait renvoyer le vecteur de représentations vectorielles continues, qui ressemble à un tableau de floats, pour la description du jouet, comme indiqué ci-dessous:

Remarque:Les projets Google Cloud récemment créés dans le cadre de la version sans frais peuvent rencontrer des problèmes de quota concernant le nombre de requêtes d'intégration autorisées par seconde pour les modèles de représentation vectorielle continue. Nous vous suggérons d'utiliser une requête de filtre pour l'ID, puis de choisir de manière sélective entre un et cinq enregistrements, et ainsi de suite, lors de la génération de la représentation vectorielle continue.

6. Effectuer une recherche vectorielle

Maintenant que la table, les données et les représentations vectorielles continues sont prêtes, nous allons effectuer la recherche vectorielle en temps réel pour le texte de recherche de l'utilisateur.

Supposons que l'utilisateur demande:

"I want a white plush teddy bear toy with a floral pattern"

Vous pouvez trouver des correspondances en exécutant la requête ci-dessous:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Examinons cette requête en détail:

Dans cette requête,

Le texte de recherche de l'utilisateur est "I want a white plush teddy bear toy with a floral pattern."
Nous le convertissons en représentations vectorielles continues dans la méthode embedding() à l'aide du modèle text-embedding-005. Cette étape doit vous sembler familière après la dernière, où nous avons appliqué la fonction de représentation vectorielle continue à tous les éléments de la table.
"<=>" représente l'utilisation de la méthode de distance SIMILARITÉ COSINE. Vous trouverez toutes les mesures de similarité disponibles dans la documentation de pgvector.
Nous convertissons le résultat de la méthode de représentation vectorielle continue en type de vecteur pour le rendre compatible avec les vecteurs stockés dans la base de données.
LIMIT 5 signifie que nous voulons extraire les 5 voisins les plus proches pour le texte de recherche.

Le résultat se présente comme suit:

Comme vous pouvez le constater dans vos résultats, les correspondances sont assez proches du texte de recherche. Essayez de modifier le texte pour voir comment les résultats changent.

7. Préparer AlloyDB pour l'interaction avec la boîte à outils

Pour préparer la configuration de la boîte à outils, nous allons activer la connectivité IP publique dans notre instance AlloyDB afin que le nouvel outil puisse accéder à la base de données.

Accédez à votre instance AlloyDB, cliquez sur MODIFIER et accédez à la page "Modifier l'instance principale".
Accédez à la section "Connectivité IP publique", cochez la case "Activer l'adresse IP publique" et saisissez l'adresse IP de votre machine Cloud Shell.
Pour obtenir l'adresse IP de votre machine Cloud Shell, accédez au terminal Cloud Shell et saisissez ifconfig. À partir du résultat, identifiez l'adresse inet eth0 et remplacez les deux derniers chiffres par 0.0 par une taille de masque '/16'. Exemple : "XX.XX.0.0/16", où XX correspond à des nombres.
Collez cette adresse IP dans la zone de texte "Réseaux" des réseaux externes autorisés de la page "Modifier l'instance".

Cliquez sur METTRE À JOUR L'INSTANCE lorsque vous avez terminé.

Cette opération prend quelques minutes.

8. MCP Toolbox pour l'installation de bases de données

Vous pouvez créer un dossier de projet pour stocker les détails de l'outil. Dans ce cas, puisque nous travaillons sur les données des magasins de jouets, nous allons créer un dossier nommé "toystore" et y accéder. Accédez au terminal Cloud Shell et vérifiez que votre projet est sélectionné et affiché dans l'invite du terminal. Exécutez la commande suivante à partir du terminal Cloud Shell:

mkdir toystore

cd toystore

Exécutez la commande suivante pour télécharger et installer toolbox dans votre nouveau dossier:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Basculez vers l'éditeur Cloud Shell. Développez le dossier "toystore" et créez un fichier nommé tools.yaml. Copiez le contenu ci-dessous. Remplacez YOUR_PROJECT_ID et vérifiez si toutes les autres informations de connexion sont correctes.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

Dans cet outil, nous cherchons simplement à trouver la correspondance la plus proche du texte recherché par l'utilisateur (description personnalisée du jouet) et à renvoyer son prix. Vous pouvez également le modifier pour trouver le prix moyen des cinq jouets les plus proches:

select avg(price) from ( SELECT price FROM jouets ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

La définition de l'outil est maintenant terminée.

Pour en savoir plus sur la configuration de votre fichier tools.yaml, consultez cette documentation.

Passez au terminal Cloud Shell et saisissez la commande suivante pour démarrer le serveur Toolbox avec la configuration de vos outils:

./toolbox --tools_file "tools.yaml"

Si vous ouvrez le serveur en mode Aperçu sur le Web dans le cloud, vous devriez voir le serveur de la boîte à outils opérationnel avec votre nouvel outil nommé get-toy-price..

9. Déploiement Cloud Run de la boîte à outils MCP pour les bases de données

Déployons-le sur Cloud Run pour que vous puissiez l'utiliser concrètement.

Suivez les instructions de cette page une par une jusqu'à atteindre la commande gcloud run deploy toolbox qui se trouve en troisième point dans la section "Déployer sur Cloud Run". Vous avez besoin de la première option, et non de la seconde, qui est utilisée lorsque vous utilisez une méthode de réseau VPC.
Une fois le déploiement réussi, vous recevrez un point de terminaison déployé Cloud Run pour votre serveur de boîte à outils. Testez-le avec une commande CURL.

Conseils :

Suivez attentivement les instructions fournies sur la page et ne manquez pas cette étape.

Vous êtes prêt à utiliser l'outil que vous venez de déployer dans votre application agent.

10. Connecter votre application à MCP Toolbox pour les bases de données

Dans cette partie, nous allons créer une petite application pour tester votre outil afin d'interagir avec les besoins de l'application et de récupérer la réponse.

Accédez à Google Colab et ouvrez un nouveau notebook.
Exécutez la commande suivante dans votre notebook.

!pip install toolbox-core
from toolbox_core import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

# Invoke the tool with a search text to pass as the parameter
 result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

Vous devriez obtenir le résultat suivant:

Il s'agit de l'outil appelé explicitement dans une application Python qui utilise le kit d'outils toolbox-langchain..

Si vous souhaitez utiliser cet outil et le lier à un agent dans une application intégrée LangGraph, vous pouvez le faire facilement à l'aide du kit d'outils langgraph.
Pour en savoir plus, consultez les extraits de code.

11. Adoptez le cloud !

Encapsulons cet extrait de code Python dans une fonction Cloud Run pour la rendre sans serveur.

Copiez le code source du dossier du dépôt de code pour accéder à Cloud Functions.
Accédez à la console Cloud Run Functions (Fonctions Cloud Run), puis cliquez sur CRÉER UNE FONCTION.
Conservez-le non authentifié pour l'application de démonstration et sélectionnez l'environnement d'exécution Python 3.11 à la page suivante.
Copiez les fichiers main.py et requirements.txt à partir du dépôt source partagé à l'étape 1 et collez-les dans les fichiers respectifs.
Remplacez l'URL du serveur dans le fichier main.py par l'URL de votre serveur.
Déployez la fonction. Vous disposez ainsi d'un point de terminaison REST permettant d'accéder à l'outil de prédiction de prix dans l'application Web du magasin de jouets.
Votre point de terminaison doit se présenter comme suit:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

Vous pouvez le tester directement dans la console Cloud Functions en accédant à l'onglet TEST et en saisissant la requête suivante:

{

           "search": "White plush toy"

}

Cliquez sur TESTER LA FONCTION ou exécutez la commande dans le terminal Cloud Shell de votre choix. Le résultat doit s'afficher à droite, sous le titre "Output" (Résultat) :

12. Félicitations

Félicitations ! Vous venez de créer un outil robuste et véritablement modulaire qui peut interagir avec des bases de données, des plates-formes et des frameworks d'orchestration d'IA générative pour vous aider à concevoir votre application agent.

Signaler une erreur