Questo documento descrive come connettere l'istanza Spanner agli IDE che supportano il protocollo di contesto del modello (MCP). MCP è un protocollo aperto per connettere modelli linguistici di grandi dimensioni (LLM) a origini dati come Spanner. Dopo la connessione, gli agenti LLM possono eseguire query e interagire con l'istanza Spanner.
Questo documento descrive la procedura di connessione per i seguenti IDE:
- Claude Code
- Claude per computer
- Cline (estensione VS Code)
- Cursore
- Visual Studio Code (Copilot)
- Windsurf (Codium)
- Gemini CLI
- Gemini Code Assist
Prima di iniziare
Nella console Google Cloud , nella pagina del selettore di progetti, seleziona o crea un progetto Google Cloud .
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud .
Configurare l'istanza Spanner
Configura i ruoli e le autorizzazioni richiesti per completare questa attività. L'utente che richiama gli agenti LLM deve disporre del ruolo Utente database Spanner (
roles/spanner.databaseUser) o di autorizzazioni di Identity and Access Management equivalenti per connettersi all'istanza. Questo ruolo è obbligatorio a livello di database.Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
Installare la casella degli strumenti MCP
Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione 0.7.0 o successive:
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
Rendi eseguibile il file binario:
chmod +x toolboxVerifica l'installazione:
./toolbox --version
Configurare l'IDE MCP
Claude Code
1. Installa Claude Code.
2. Crea il file
.mcp.json nella radice del progetto, se non esiste. 3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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 per computer
1. Apri Claude per il computer e vai a Impostazioni.
2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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. Riavvia Claude per il desktop.
5. Nella nuova schermata della chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.
Cline
1. Apri l'estensione Cline in VS Code e fai clic sull'icona Server MCP.
2. Tocca Configura server MCP per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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"
}
}
}
}
Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.
Cursore
1. Se non esiste, crea la directory
.cursor nella radice del progetto. 2. Crea il file
.cursor/mcp.json se non esiste e aprilo.3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.
Visual Studio Code (Copilot)
1. Apri VS Code e crea la directory
.vscode nella radice del progetto, se non esiste. 2. Crea il file
.vscode/mcp.json se non esiste e aprilo. 3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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. Apri Windsurf e vai all'assistente per le cascate.
2. Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner, sostituisci le variabili di ambiente con i tuoi valori e salva il file:
Spanner con dialetto 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 con dialetto 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"
}
}
}
}
Interfaccia a riga di comando Gemini
1. Installa la Gemini CLI.
2. Nella directory principale del progetto, crea una cartella denominata
.gemini e, al suo interno, un file settings.json.3. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner nel file
settings.json.4. Sostituisci le seguenti variabili con i tuoi valori:
PROJECT_ID: il tuo ID progetto Google Cloud .INSTANCE_NAME: il nome dell'istanza Spanner.DATABASE_NAME: il nome del database Spanner.
Spanner con dialetto 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 con dialetto 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"
}
}
}
}
Gemini Code Assist
1. Installa l'estensione Gemini Code Assist in VS Code.
2. Attiva la modalità agente e passa al modello di agente Gemini.
3. Nella directory principale del progetto, crea una cartella denominata
.gemini e, al suo interno, un file settings.json.4. Aggiungi una delle seguenti configurazioni in base al dialetto Spanner nel file
settings.json.5. Sostituisci le seguenti variabili con i tuoi valori:
PROJECT_ID: il tuo ID progetto Google Cloud .INSTANCE_NAME: il nome dell'istanza Spanner.DATABASE_NAME: il nome del database Spanner.
Spanner con dialetto 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 con dialetto 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"
}
}
}
}
Interagire con l'istanza Spanner
Il tuo IDE è ora connesso a Spanner utilizzando MCP. L'agente LLM ora può elencare tabelle, creare tabelle o definire ed eseguire altre istruzioni SQL.
Sono disponibili i seguenti strumenti per il LLM:
- list_tables: elenca le tabelle e le descrizioni
- execute_sql: esegui qualsiasi istruzione SQL
- execute_sql_dql: esegui l'istruzione SQL DQL