Utiliser Spanner avec MCP Toolbox for Databases, la CLI Gemini et d'autres agents

Ce document explique comment connecter votre instance Spanner à différents outils pour les développeurs compatibles avec le Model Context Protocol (MCP).

Nous vous recommandons d'utiliser l'extension Spanner dédiée pour Gemini CLI. Cette extension évite d'avoir à configurer une connexion serveur distincte. Vous pouvez configurer Gemini Code Assist pour qu'il utilise la Gemini CLI, ce qui offre des avantages de configuration similaires dans votre IDE. Pour en savoir plus, consultez Extension Gemini CLI – Spanner.

D'autres IDE et outils pour les développeurs compatibles avec le MCP peuvent se connecter via MCP Toolbox for Databases. MCP 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.

Utiliser l'extension Gemini CLI dans Spanner

L'intégration de Spanner à Gemini CLI se fait via une extension Open Source qui offre des fonctionnalités supplémentaires par rapport à la connexion standard à la boîte à outils MCP. L'extension propose un processus d'installation et un ensemble d'outils, en plus de fournir des informations détaillées sur l'installation, la configuration et des exemples d'utilisation. Si vous utilisez l'extension Gemini CLI, vous n'avez pas besoin d'installer MCP Toolbox. Pour en savoir plus, consultez Extension Gemini CLI – Spanner.

L'extension spanner inclut des outils permettant de lister les tables et d'exécuter des instructions SQL et SQL DQL.

Outils Exemple de requête en langage naturel
list_tables Quelles tables sont disponibles dans mon instance Spanner ?
execute_sql Insérez des données de test dans la table "products".
execute_sql_dql Quels produits de la catégorie "Électronique" sont vendus en Amérique ?

Avant de commencer

  1. Dans la console Google Cloud , sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud .

  2. Assurez-vous que la facturation est activée pour votre projet Google Cloud .

Configurer l'instance Spanner

  1. Activez l'API Spanner dans le projet Google Cloud .

  2. Créez ou sélectionnez une instance et une base de données Spanner.

  3. Configurez les rôles et autorisations requis pour effectuer cette tâche. L'utilisateur qui appelle les agents LLM a besoin des rôles suivants au niveau de la base de données :

    • Lecteur de bases de données Cloud Spanner (roles/spanner.databaseReader) pour exécuter des requêtes DQL et lister les tables.

    • Utilisateur de bases de données Cloud Spanner (roles/spanner.databaseUser) pour exécuter des requêtes LMD.

  4. Configurez les identifiants par défaut de l'application pour votre environnement.

Installer MCP Toolbox

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

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/version/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/version/windows/amd64/toolbox

  2. Rendez le binaire exécutable :

    chmod +x toolbox

  3. Vérifiez l'installation :

    ./toolbox --version

Configurer l'outil Agent

Cette section explique comment configurer différents outils pour les développeurs afin de vous connecter à votre instance Spanner. Sélectionnez votre outil pour l'agent parmi les options suivantes :

CLI Gemini

  1. Installez la Gemini CLI.
  2. Installez l'extension Spanner pour Gemini CLI à partir du dépôt GitHub à l'aide de la commande suivante :
    3.   gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Définissez les variables d'environnement suivantes pour vous connecter à votre instance Spanner :
        export SPANNER_PROJECT="PROJECT_ID"
    export SPANNER_INSTANCE="INSTANCE_NAME"
    export SPANNER_DATABASE="DATABASE_NAME"
    export SPANNER_DIALECT="DIALECT_NAME"
    Remplacez les éléments suivants :
    • PROJECT_ID : ID de votre projet Google Cloud .
    • INSTANCE_NAME : nom de votre instance Spanner.
    • DATABASE_NAME : nom de votre base de données Spanner.
    • DIALECT_NAME : votre dialecte Spanner SQL. Accepte googlesql ou postgresql. La valeur par défaut est googlesql si elle n'est pas définie.
  4. Démarrez Gemini CLI en mode interactif : 
        gemini
    La CLI charge automatiquement l'extension Spanner pour Gemini CLI et ses outils, que vous pouvez utiliser pour interagir avec votre base de données.

Gemini Code Assist

Nous vous recommandons vivement de configurer Gemini Code Assist pour qu'il utilise la CLI Gemini, car cette approche élimine la nécessité de configurer manuellement un serveur MCP. Toutefois, les instructions pour configurer manuellement un serveur MCP sont toujours disponibles dans la section suivante :


1. Installez l'extension Gemini Code Assist dans VS Code.
2. Activez le mode Agent et définissez le modèle d'agent sur Gemini.
3. Dans le répertoire racine de votre projet, créez un dossier nommé .gemini, puis un fichier settings.json à l'intérieur.
4. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner dans le fichier settings.json.
5. Remplacez les variables suivantes par vos valeurs :
  • PROJECT_ID : ID de votre projet Google Cloud .
  • INSTANCE_NAME : nom de votre instance Spanner.
  • DATABASE_NAME : nom de votre base de données Spanner.
6. Enregistrez le fichier.

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code


1. Installez Claude Code.
2. Créez le fichier .mcp.json à la racine de votre projet, s'il n'existe pas.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude pour ordinateur


1. Ouvrez Claude pour ordinateur et accédez à Paramètres.
2. Dans l'onglet Développeur, cliquez sur Modifier la configuration pour ouvrir le fichier de configuration.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Redémarrez Claude pour ordinateur.
5. 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 cliquez sur l'icône Serveurs MCP.
2. Appuyez sur "Configurer les serveurs MCP" pour ouvrir le fichier de configuration.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Un état actif vert s'affiche une fois que le serveur est 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 et ouvrez-le.
3. Ajoutez l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. 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 l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

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 l'une des configurations suivantes en fonction de votre dialecte Spanner, remplacez les variables d'environnement par vos valeurs et enregistrez le fichier :

Spanner avec le dialecte GoogleSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner avec le dialecte PostgreSQL : 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Contacter Antigravity

Vous pouvez connecter Spanner à Antigravity de plusieurs façons :

  • Utiliser le MCP Store
  • Utiliser une configuration personnalisée

Boutique MCP

La méthode la plus recommandée pour se connecter à Antigravity consiste à utiliser le MCP Store intégré.

  1. Ouvrez Antigravity, puis le panneau de l'agent de l'éditeur.
  2. Cliquez sur l'icône Menu en haut du panneau, puis sélectionnez Serveurs MCP.
  3. Recherchez Spanner dans la liste des serveurs disponibles, puis cliquez sur Install (Installer).
  4. Suivez les étapes à l'écran pour autoriser Antigravity à accéder à votre projet Google Cloud. Cela permet à Antigravity d'accéder à l'instance Spanner de votre projet.

Une fois que vous avez installé le serveur Spanner dans le MCP Store, les ressources et les outils du serveur sont disponibles dans l'éditeur.

Configuration personnalisée

Pour vous connecter à un serveur MCP personnalisé, procédez comme suit :

  1. Ouvrez Antigravity, puis le panneau de l'agent de l'éditeur.
  2. Cliquez sur l'icône Menu en haut du panneau, puis sélectionnez Serveurs MCP.
  3. Cliquez sur Gérer les serveurs MCP > Afficher la configuration brute pour ouvrir le fichier mcp_config.json.
  4. Ajoutez la configuration suivante, remplacez les variables d'environnement par vos valeurs, puis enregistrez.
{
  "mcpServers": {
    "spanner": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME",
          "SPANNER_DIALECT": "DIALECT_NAME"
      }
    }
  }
}

Une fois le serveur MCP personnalisé configuré, les ressources et les outils du serveur Spanner sont disponibles pour l'éditeur.

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • INSTANCE_NAME : nom de votre instance Spanner.
  • DATABASE_NAME : nom de votre base de données Spanner.
  • DIALECT_NAME : votre dialecte Spanner SQL. Accepte googlesql ou postgresql. Si vous ne spécifiez pas de dialecte, la valeur par défaut est googlesql.