Utiliser AlloyDB pour PostgreSQL avec MCP, Gemini CLI et d'autres agents

Ce document explique comment connecter votre instance AlloyDB à différents agents compatibles avec le Model Context Protocol (MCP).

Nous vous recommandons d'utiliser l'extension AlloyDB dédiée pour Gemini CLI. La CLI Gemini intègre le serveur MCP sous-jacent directement dans l'extension. Vous n'avez donc pas besoin de configurer un serveur distinct. Vous pouvez configurer Gemini Code Assist pour qu'il utilise la CLI Gemini, ce qui offre des avantages de configuration similaires dans votre IDE.

Vous pouvez également connecter d'autres IDE et agents compatibles avec le protocole MCP via MCP Toolbox for Databases. Toolbox est un serveur MCP Open Source conçu pour connecter les agents d'IA à vos données. Il gère des tâches telles que l'authentification et le regroupement de connexions, ce qui vous permet d'interagir avec vos données en langage naturel directement depuis votre IDE.

Avant de commencer

Pour vous connecter à votre instance AlloyDB et utiliser les outils disponibles, vous devez disposer de l'un des rôles Identity and Access Management (IAM) suivants ou d'un rôle personnalisé avec des autorisations équivalentes :

Tâche Nom du rôle Rôle IAM (Identity and Access Management) requis
Utiliser des outils en lecture seule pour lister et obtenir des ressources AlloyDB Lecteur AlloyDB roles/alloydb.viewer
Se connecter à une instance et exécuter des requêtes Client Cloud AlloyDB roles/alloydb.client
Consommateur Service Usage roles/serviceusage.serviceUsageConsumer
effectuer des tâches administratives (comme créer ou gérer des clusters, des instances et des utilisateurs) ; Administrateur AlloyDB roles/alloydb.admin
Utiliser l'extension d'observabilité Lecteur Monitoring roles/monitoring.viewer

Avant de pouvoir vous connecter à votre instance AlloyDB, suivez les étapes ci-dessous pour configurer votre projet et votre base de données.

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

  2. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Activez les APIs Cloud nécessaires pour créer une instance AlloyDB et vous y connecter.

    Activer les API

    1. À l'étape Confirmer le projet, cliquez sur Suivant pour confirmer le nom du projet que vous allez modifier.

    2. À l'étape Activer les API, cliquez sur Activer pour activer les éléments suivants :

      • API AlloyDB
      • API Compute Engine
      • API Cloud Resource Manager
      • API Service Networking

      L'API Service Networking est requise si vous prévoyez de configurer la connectivité réseau à AlloyDB à l'aide d'un réseau VPC qui réside dans le même projet Google Cloud qu'AlloyDB.

      Les API Compute Engine et Cloud Resource Manager sont requises si vous prévoyez de configurer la connectivité réseau à AlloyDB à l'aide d'un réseau VPC résidant dans un autre projet Google Cloud .

  7. Créez ou sélectionnez un cluster et son instance principale.
  8. Configurez les identifiants par défaut de l'application pour votre environnement.
  9. Créez ou réutilisez un utilisateur de base de données. Préparez-vous à saisir le nom d'utilisateur et le mot de passe.

    10. Utiliser les extensions de la CLI Gemini pour AlloyDB

    La CLI Gemini est un agent d'IA Open Source conçu pour vous aider dans vos workflows de développement en vous assistant pour le codage, le débogage, l'exploration de données et la création de contenu. Sa mission est de fournir une interface agentique pour interagir avec les services Data Cloud et les bases de données Open Source populaires.

    L'intégration à la CLI Gemini se fait par le biais d'extensions dédiées qui offrent des fonctionnalités supplémentaires par rapport à une connexion MCP Toolbox standard. Les sections suivantes décrivent les extensions alloydb et alloydb-observability, qui proposent un processus d'installation et un ensemble d'outils. Les extensions Open Source contiennent des informations détaillées sur l'installation, la configuration et des exemples d'utilisation. Pour en savoir plus, consultez Extension Gemini CLI – AlloyDB pour PostgreSQL.

    L'extension alloydb inclut des outils permettant d'interroger la base de données, de gérer les ressources AlloyDB et de surveiller l'état de la base de données.

    Catégorie Outils Exemple de requête en langage naturel
    Opérations de base de données list_tables Affiche toutes les tables de la base de données actuelle.
    execute_sql Exécutez la requête : SELECT * FROM products WHERE category = 'electronics';
    list_active_queries Quelles requêtes sont exécutées sur la base de données ?
    get_query_plan Explique le plan de requête pour "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
    list_available_extensions Quelles extensions puis-je installer ?
    list_installed_extensions Répertoriez toutes les extensions installées.
    Gestion des ressources
    clusters, instances, utilisateurs    		 create_cluster Créez un cluster AlloyDB nommé sales-quarterly-db dans la région us-east1.
    get_cluster Obtenez les détails du cluster sales-quarterly-db.
    list_clusters Liste tous mes clusters AlloyDB.
    create_instance Créez une instance de lecture dans le cluster sales-quarterly-db.
    get_instance Affiche-moi les informations de l'instance sales-quarterly-db-rp.
    list_instances Répertoriez toutes les instances du cluster sales-quarterly-db.
    create_user Créez un utilisateur de base de données nommé reporting_user.
    get_user Obtenez les informations de l'utilisateur reporting_user.
    list_users Répertoriez tous les utilisateurs de la base de données.
    wait_for_operation Quel est l'état de l'opération operation-163562789 ?
    État et maintenance de la base de données list_autovacuum_configurations Affiche-moi la configuration autovacuum actuelle.
    list_memory_configurations Quelles sont les configurations de mémoire actuelles pour l'instance principale ?
    list_top_bloated_tables Liste les cinq tables les plus volumineuses.
    list_replication_slots Affichez tous les emplacements de réplication actifs.
    list_invalid_indexes Recherchez les index non valides dans la base de données orders.

    L'extension alloydb-observability fournit une interface unifiée pour gérer et surveiller les performances et l'état des bases de données directement depuis la CLI Gemini.

    Catégorie Outils Exemple de requête en langage naturel
    Observabilité get_system_metrics Quelles sont les métriques système, comme l'utilisation du processeur, pour la dernière heure ?
    get_query_metrics Affiche-moi les métriques sur les performances des requêtes des 15 dernières minutes.

    Vous pouvez utiliser l'extension Gemini CLI pour AlloyDB de deux manières :

    • Un outil de ligne de commande autonome
    • Intégration à votre IDE avec Gemini Code Assist

    CLI Gemini

    1. Installez la Gemini CLI.
    2. Installez l'extension AlloyDB pour Gemini CLI à partir du dépôt GitHub à l'aide de la commande suivante : 
      gemini extensions install https://github.com/gemini-cli-extensions/alloydb
    3. Définissez des variables d'environnement pour vous connecter à votre instance 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"

      L'extension Gemini CLI pour AlloyDB utilise par défaut vos [identifiants par défaut de l'application (ADC)](/authentication/application-default-credentials) pour l'authentification. Si vous souhaitez vous connecter en tant qu'utilisateur de base de données, définissez les variables d'environnement facultatives suivantes :

      #Optional: Set for database user authentication
export ALLOYDB_POSTGRES_USER="USERNAME"
export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"

      Pour vous connecter à l'aide d'une adresse IP privée, vous devez également définir la variable d'environnement suivante :

      export ALLOYDB_POSTGRES_IP_TYPE="private"
    4. Démarrez la CLI Gemini en mode interactif : 
      gemini
      La CLI charge automatiquement l'extension AlloyDB pour l'extension CLI Gemini et ses outils, que vous pouvez utiliser pour interagir avec votre base de données.

    Gemini Code Assist

    Nous vous recommandons de configurer Gemini Code Assist pour qu'il utilise la CLI Gemini. Cette approche élimine la nécessité de configurer manuellement un serveur MCP.

    1. Assurez-vous d'avoir installé et configuré la Gemini CLI et l'extension alloydb.
    2. Configurez Gemini Code Assist pour utiliser la CLI Gemini.
    3. Commencez à interagir avec votre instance AlloyDB en langage naturel directement dans le chat Gemini Code Assist.

    Se connecter à d'autres IDE à l'aide de MCP Toolbox for Databases

    Cette section explique comment vous connecter à votre instance AlloyDB à partir de différents agents à l'aide de la boîte à outils MCP pour les bases de données. Toolbox agit comme un serveur MCP (Model Context Protocol) Open Source qui se situe entre votre IDE et votre base de données, et fournit un plan de contrôle pour vos outils d'IA. Cette section explique comment se connecter à une instance AlloyDB à l'aide d'une adresse IP publique ou privée. Par défaut, Toolbox utilise une adresse IP publique, mais vous pouvez configurer une connexion IP privée en définissant la variable d'environnement ALLOYDB_POSTGRES_IP_TYPE, comme indiqué dans les exemples de configuration.

    Installer MCP Toolbox for Databases

    Pour connecter votre IDE à AlloyDB, vous devez installer MCP Toolbox for Databases, un serveur Open Source qui connecte les agents d'IA à vos données.

    1. Téléchargez la dernière version de Toolbox en tant que fichier binaire. Sélectionnez le fichier binaire correspondant à votre système d'exploitation et à l'architecture de votre processeur. Vous devez utiliser la version v0.15.0 ou ultérieure de Toolbox.

      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. Rendez le binaire exécutable.

      chmod +x toolbox

    3. Vérifiez l'installation.

      ./toolbox --version

    Configurer votre client

    Sélectionnez votre outil d'agent parmi les options suivantes :

    Code Claude

    1. Installez Claude Code.
    2. Créez le fichier .mcp.json à la racine de votre projet, s'il n'existe pas.
    3. Ajoutez la configuration, remplacez les variables d'environnement par vos valeurs, puis enregistrez.

    {
  "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"
      }
    }
  }
}

    Claude sur ordinateur

    1. Ouvrez Claude Desktop et accédez à Settings (Paramètres).
    2. Dans l'onglet Développeur, cliquez sur Modifier la configuration pour ouvrir le fichier de configuration.
    3. Ajoutez la configuration, remplacez les variables d'environnement par vos valeurs, puis enregistrez.

    {
  "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"
      }
    }
  }
}
    1. Redémarrez Claude Desktop.
    2. Le nouvel écran de chat affiche une icône en forme de marteau (MCP) avec le nouveau serveur MCP.

    Cline

    1. Ouvrez l'extension Cline dans VS Code, puis appuyez sur l'icône Serveurs MCP.
    2. Cliquez sur Configurer les serveurs MCP pour ouvrir le fichier de configuration.
    3. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.

    {
  "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"
      }
    }
  }
}

    Un état actif vert s'affiche une fois le serveur connecté.

    Cursor

    1. Créez le répertoire .cursor dans la racine de votre projet s'il n'existe pas.
    2. Créez le fichier .cursor/mcp.json s'il n'existe pas, puis ouvrez-le.
    3. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.
    {
  "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"
      }
    }
  }
}
    1. Ouvrez Cursor, puis accédez à Settings > Cursor Settings > MCP (Paramètres > Paramètres du curseur > MCP). Un état actif vert s'affiche lorsque le serveur se connecte.

    Visual Studio Code (Copilot)

    1. Ouvrez VS Code et créez le répertoire .vscode à la racine de votre projet s'il n'existe pas.
    2. Créez le fichier .vscode/mcp.json s'il n'existe pas, puis ouvrez-le.
    3. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.
    {
  "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"
      }
    }
  }
}

    Windsurf

    1. Ouvrez Windsurf et accédez à l'assistant Cascade.
    2. Cliquez sur l'icône MCP, puis sur Configurer pour ouvrir le fichier de configuration.
    3. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.
    {
  "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"
      }
    }
  }
}