Codelab: server MCP Spanner

1. Panoramica

Questo codelab mostra come eseguire query grafiche su Spanner utilizzando gemini-cli e i server Model Context Protocol (MCP) di Google. Integrando il database multimodello di Spanner, incluso Spanner Graph, con il servizio MCP gestito, puoi utilizzare il linguaggio naturale per scoprire relazioni nascoste nei tuoi dati, come cerchie di frode o dipendenze della supply chain, in un unico database senza scrivere manualmente query GQL (Graph Query Language) o SQL complesse.

Cosa imparerai a fare

Come configurare un database multimodello Spanner, incluso Spanner Graph per MCP.
Come connettere Gemini CLI a un endpoint del servizio Spanner remoto gestito.
Come utilizzare il linguaggio naturale per generare automaticamente codice SQL integrato con GQL per eseguire attraversamenti del grafo e corrispondenza di pattern insieme a operazioni relazionali.
Best practice per proteggere i dati dei grafici nei workflow AI.

Prerequisiti

Un progetto Google Cloud con la fatturazione abilitata.
Accesso a un terminale (come Cloud Shell). Consulta questo codelab.
L'interfaccia a riga di comando gcloud installata e autenticata.
Accesso a Gemini CLI.

NOTA: eseguirai tutti i comandi in un terminale Unix. Consulta i prerequisiti riportati sopra per accedere a un terminale con accesso a gcloud con l'autenticazione corretta.

2. Configura l'ambiente multimodello di Spanner

MCP gestito funziona meglio quando lo schema del database è predefinito. Creeremo un grafico finanziario "Rilevamento frodi" basato sugli esempi di Spanner Graph.

Abilita API

export PROJECT_ID="YOUR_PROJECT_ID"

gcloud config set project ${PROJECT_ID}

# Enable Spanner's MCP endpoint
gcloud beta services mcp enable spanner.googleapis.com --project=${PROJECT_ID}

Crea lo schema del database

Crea un'istanza e un database con tabelle di database e un grafico delle proprietà. Questo schema tiene traccia di Account, Persone e dei Trasferimenti tra loro.

NOTA: puoi eseguire queste istruzioni DDL da Spanner Studio. Consulta questo link per informazioni sulla creazione e l'esecuzione di query su un database Spanner dalla console GCP.

CREATE TABLE Account (
  id INT64 NOT NULL,
  create_time TIMESTAMP,
  is_blocked BOOL,
  nick_name STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE Person (
  id INT64 NOT NULL,
  name STRING(MAX),
  birthday TIMESTAMP,
  country STRING(MAX),
  city STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE AccountTransferAccount (
  id INT64 NOT NULL,
  to_id INT64 NOT NULL,
  amount FLOAT64,
  create_time TIMESTAMP NOT NULL,
  order_number STRING(MAX),
  FOREIGN KEY(to_id) REFERENCES Account(id),
) PRIMARY KEY(id, to_id, create_time),
  INTERLEAVE IN PARENT Account ON DELETE CASCADE;

CREATE TABLE PersonOwnAccount (
  id INT64 NOT NULL,
  account_id INT64 NOT NULL,
  create_time TIMESTAMP,
  FOREIGN KEY(account_id) REFERENCES Account(id),
) PRIMARY KEY(id, account_id),
  INTERLEAVE IN PARENT Person ON DELETE CASCADE;

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES(
    Account
      KEY(id)
      LABEL Account PROPERTIES(
        create_time,
        id,
        is_blocked,
        nick_name),

    Person
      KEY(id)
      LABEL Person PROPERTIES(
        birthday,
        city,
        country,
        id,
        name)
  )
  EDGE TABLES(
    AccountTransferAccount
      KEY(id, to_id, create_time)
      SOURCE KEY(id) REFERENCES Account(id)
      DESTINATION KEY(to_id) REFERENCES Account(id)
      LABEL Transfers PROPERTIES(
        amount,
        create_time,
        id,
        order_number,
        to_id),

    PersonOwnAccount
      KEY(id, account_id)
      SOURCE KEY(id) REFERENCES Person(id)
      DESTINATION KEY(account_id) REFERENCES Account(id)
      LABEL Owns PROPERTIES(
        account_id,
        create_time,
        id)
  );

Compilare i dati

Inserisci persone

INSERT INTO Person (id, name, birthday, country, city) VALUES
(1, 'Alex', '1990-01-01T00:00:00Z', 'USA', 'New York'),
(2, 'Lee', '1985-05-15T00:00:00Z', 'USA', 'San Francisco'),
(3, 'Dana', '1995-08-20T00:00:00Z', 'Canada', 'Vancouver'),
(4, 'Maria', '1992-04-15T00:00:00Z', 'USA', 'Chicago'),
(5, 'David', '1988-11-20T00:00:00Z', 'Canada', 'Toronto');

Inserisci account

INSERT INTO Account (id, create_time, is_blocked, nick_name) VALUES
(7, '2020-01-10T14:22:20.222Z', false, 'Vacation Fund'),
(16, '2020-01-28T01:55:09.206Z', true, 'Vacation Fund'),
(20, '2020-02-18T13:44:20.655Z', false, 'Rainy Day Fund'),
(25, '2023-01-15T10:00:00Z', false, 'Savings'),
(30, '2023-02-20T11:00:00Z', false, 'Checking');

Collegare persone agli account

INSERT INTO PersonOwnAccount (id, account_id, create_time) VALUES
(1, 7, '2020-01-10T14:22:20.222Z'),
(2, 16, '2020-01-28T01:55:09.206Z'),
(3, 20, '2020-02-18T13:44:20.655Z'),
(4, 25, '2023-01-15T10:00:00Z'),
(5, 30, '2023-02-20T11:00:00Z');

Aggiungere trasferimenti

INSERT INTO AccountTransferAccount (id, to_id, amount, create_time, order_number) VALUES
(7, 16, 300, '2024-02-28T10:00:00Z', 'ORD123'),
(7, 16, 100, '2024-02-29T11:00:00Z', 'ORD124'),
(16, 20, 300, '2024-02-29T12:00:00Z', 'ORD125'),
(20, 7, 500, '2024-02-29T13:00:00Z', 'ORD126'),
(20, 16, 200, '2024-02-29T14:00:00Z', 'ORD127'),
(7, 25, 150.75, '2024-03-01T12:00:00Z', 'ORD456'),
(25, 30, 200.00, '2024-03-02T14:30:00Z', 'ORD457'),
(30, 16, 50.25, '2024-03-03T16:00:00Z', 'ORD458');

3. Configura l'interfaccia a riga di comando di Gemini e Spanner MCP

Il lab è progettato per utilizzare Gemini CLI come agente principale per eseguire la maggior parte delle azioni e il primo passaggio consiste nel configurarlo per funzionare con il server Spanner MCP remoto. Inoltre, è consigliabile utilizzare l'ultima versione di Gemini CLI e l'ultima versione di Gemini, ad esempio Gemini 3 Pro o Gemini 3 Flash (attualmente in anteprima).

Se hai già l'ultima versione di Gemini CLI e l'hai configurata per utilizzare gli ultimi modelli Gemini, puoi saltare i due passaggi successivi e andare direttamente al passaggio 3.

Ottieni la chiave API Gemini

Per utilizzare i modelli Gemini più recenti nella tua Gemini CLI, devi configurarla con l'autenticazione con chiave API. Possiamo ottenere la chiave API in Google AI Studio

Vai a Google AI Studio -> Ottieni chiave API nel browser.
Sul lato destro dello schermo, fai clic sul pulsante Create API key.
Nella finestra popup, scegli il tuo progetto o importalo se non è visibile.

Crea la chiave API.
Puoi copiare la chiave utilizzando il pulsante di copia sul lato destro.

La chiave è preparata e ora possiamo utilizzarla per Gemini CLI

Configura Gemini CLI

Gemini CLI può essere configurata tramite il file di configurazione delle impostazioni o in modo interattivo utilizzando il comando /settings. Vogliamo che le nostre impostazioni vengano mantenute nel file delle impostazioni.

Per prima cosa, creiamo una directory per il nostro progetto. Chiamiamo la directory projectspannermcp e passiamo a questa directory utilizzando i seguenti comandi.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

Nella directory creeremo una directory per i file di configurazione di Gemini ed eseguiremo tutti i nostri comandi. Per impostazione predefinita, Gemini CLI utilizza un file di configurazione dell'ambito utente e le estensioni installate nella directory ~/.gemini. Tuttavia, creeremo la nostra configurazione dell'ambito del progetto nella directory ~/projectspannermcp. Iniziamo creando la directory e i file di configurazione.

mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json

Poi apriamo il file ~/projectspannermcp/.gemini/settings.json utilizzando l'editor di Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

Nella finestra dell'editor aperta, aggiungi la seguente configurazione.

{
  "general": {
    "preferredEditor": "vscode",
    "previewFeatures": true,
    "sessionRetention": {
      "enabled": true
    }
  },
  "ide": {
    "enabled": true,
    "hasSeenNudge": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "ui": {
    "theme": "Default"
  },
  "tools": {
    "shell": {
      "enableInteractiveShell": false
    }
  }
}

Dopo aver modificato il file, puoi utilizzare ctrl+s per salvare le modifiche e tornare al terminale facendo clic sul pulsante Open Terminal.

Il file settings.json riportato sopra imposta il tipo di autenticazione della CLI Gemini come gemini-api-key e devi fornire la chiave al modello. Puoi farlo creando un file .env nella directory in cui vuoi lavorare con Gemini CLI e memorizzando la chiave API per l'autenticazione di Gemini CLI come variabile di ambiente che verrà rilevata all'avvio dell'IDE.

Modifichiamo il file utilizzando l'editor di Cloud Shell

edit ~/projectspannermcp/.env

e memorizza la chiave API creata nel passaggio "Ottieni la chiave API Gemini" riportato sopra.

GEMINI_API_KEY= <YOUR_API_KEY>

Ora puoi tornare al terminale e continuare. Il passaggio successivo consiste nell'aggiornare Gemini CLI all'ultima versione. La versione in Google Cloud Shell o nel tuo ambiente potrebbe essere obsoleta e non funzionare correttamente con le configurazioni e i servizi MCP più recenti. Pertanto, è importante aggiornare Gemini CLI all'ultima versione e avviarla. Nel terminale, esegui questo comando.

cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest

Ora puoi verificare la versione. Tieni presente che se lavori in Google Cloud Shell, ogni volta che riavvii la shell potrebbe tornare alla versione precedente. Le modifiche apportate alla Gemini CLI stessa non sono permanenti in Cloud Shell.

gemini --version

Dovrebbe essere visualizzata l'ultima versione della CLI Gemini (versione 0.27 al momento della stesura del lab). Puoi verificare l'ultima versione di Gemini CLI qui. Ora possiamo avviarlo e assicurarci che utilizzi l'ultimo modello Gemini. Esegui questo comando nella cartella del progetto per avviare Gemini CLI.

gemini

Quando Gemini CLI viene avviata, puoi controllare la versione e il modello eseguendo il comando /about nell'interfaccia. Dovresti ottenere un risultato simile a quello mostrato nell'immagine qui sotto.

Puoi vedere che utilizza l'ultimo modello Gemini-3. I passaggi riportati di seguito che mostrano le query in linguaggio naturale richiedono l'utilizzo del modello Gemini-3.

Configura Gemini CLI per utilizzare Spanner MCP

Dobbiamo aggiungere un'altra cosa al file settings.json. Innanzitutto, esci da Gemini CLI (puoi premere Ctrl+C due volte).

Nello stesso settings.json di prima, aggiungiamo il bit per configurare il server Spanner MCP. Di seguito è riportato il file settings.json completo. Nota la parte che inizia con "mcpServers".

{
 "general": {
   "preferredEditor": "vscode",
   "previewFeatures": true,
   "sessionRetention": {
     "enabled": true
   }
 },
 "ide": {
   "enabled": true,
   "hasSeenNudge": true
 },
 "security": {
   "auth": {
     "selectedType": "gemini-api-key"
   }
 },
 "ui": {
   "theme": "Default"
 },
 "tools": {
   "shell": {
     "enableInteractiveShell": false
   }
 },
 "mcpServers": {
   "spanner": {
     "httpUrl": "https://spanner.googleapis.com/mcp",
     "authProviderType": "google_credentials",
     "oauth": {
       "scopes": ["https://www.googleapis.com/auth/spanner.admin",
                  "https://www.googleapis.com/auth/spanner.data"]
     },
     "timeout": 5000
   }
 },
 "mcp": {
   "allowed": [
     "spanner"
   ]
 }
}

Prima di procedere con il passaggio successivo, autenticati

gcloud auth application-default login

Dopo l'autenticazione, riavvia gemini-cli

gemini

4. Genera query multimodali, incluse quelle incentrate sui grafi

Iniziamo elencando le istanze Spanner nel progetto configurato.

"Please list all Spanner instances in my project <project1> (replace with your project id)" (elenca tutte le istanze Spanner nel mio progetto <project1>, sostituisci con il tuo ID progetto)

Risposta:

The Spanner instances in your project are:
 [instance1]

"Elenca tutti i database in <instance1> (sostituisci con la tua istanza)"

Risposta:

The Spanner databases in [instance1] are:
  [database1]

A questo punto, chiediamo a Gemini di ricordare l'istanza/il database in cui hai eseguito le istruzioni DDL e le istruzioni di inserimento nella sezione di configurazione di Spanner:

"Supponi che tutte le query vengano inviate al database <your-db> nell'istanza <your-instance>, se non diversamente indicato"

NOTE: utilizza l'istanza/il database su cui hai eseguito le istruzioni DDL e le istruzioni di inserimento riportate sopra.

Una volta connesso, il modello Gemini comprende lo schema del grafico. Ora puoi eseguire attraversamenti sofisticati utilizzando il linguaggio naturale.

Il modello tradurrà automaticamente questi elementi in GQL (Graph Query Language):

Identificare le strutture di rete

"Descrivi la struttura del grafico delle proprietà "FinGraph". Quali sono le etichette dei nodi e dei bordi?"

Risposta:

  Node Labels
   * `Account`: Represents financial accounts.
       * Properties: id, create_time, is_blocked, nick_name
   * `Person`: Represents individuals.
       * Properties: id, name, birthday, country, city

  Edge Labels
   * `Transfers`: Represents a transfer between two Account nodes.
       * Source: Account
       * Destination: Account
       * Properties: id, to_id, amount, create_time, order_number
   * `Owns`: Represents a Person owning an Account.
       * Source: Person
       * Destination: Account
       * Properties: id, account_id, create_time

Rilevamento di frodi e cicli

"Trova eventuali trasferimenti circolari in cui il denaro è stato inviato dall'Account A e alla fine è tornato all'Account A entro 3 passaggi".

Risposta:

The analysis confirms the following circular transfers where money returns to the originating account within 3 hops:

  3-Hop Cycles
  Money travels through two intermediate accounts before returning to the origin.
   * Account 16 (Involved in multiple 3-hop paths)
   * Account 20 (Involved in multiple 3-hop paths)
   * Account 7 (Involved in multiple 3-hop paths)

These accounts are participating in circular flow patterns of varying lengths.

Analisi approfondita delle relazioni

"Identifica tutte le Persone che possiedono account che hanno inviato più di 499 $ad account di proprietà di persone diverse negli ultimi 24 mesi."

Risposta:

Dana is the only person who owns an account that has sent more than $499 to an account owned by a different person in the last 24 months.

(Specifically, her account sent exactly $500, which is the maximum transfer amount in the database).

Pathfinding

"Trova il percorso più breve di trasferimenti tra l'ID account 16 e l'ID account 20."

Risposta:

The shortest path between Account 16 and Account 20 is 1 hop.

This means there is a direct transfer from Account 16 to Account 20.

5. Complimenti!

Congratulazioni per aver completato il codelab.

Argomenti trattati

In questo codelab hai imparato a configurare gemini-cli con il server Spanner MCP ed eseguire query in linguaggio naturale sui dati di Spanner Graph per scoprire informazioni. Ecco un riepilogo delle tappe fondamentali:

Infrastruttura gestita:è stato attivato il server MCP Spanner remoto, eliminando la necessità di proxy locali o di MCP Toolbox.
Integrazione del grafico:è stato configurato un grafico delle proprietà Spanner (FinGraph) con nodi e archi per rappresentare relazioni complesse.
Strumenti nativi:l'interfaccia a riga di comando di Gemini è stata collegata direttamente all'endpoint Spanner gestito utilizzando uno schema URI standard.
SQL e GQL in linguaggio naturale:il server è stato esercitato con prompt specifici per i grafici, consentendo all'LLM di eseguire attraversamenti multihop e rilevamento dei cicli senza codifica manuale di SQL/GQL.
Pronta per l'uso aziendale:è stato esaminato il modo in cui MCP gestito fornisce un percorso scalabile e autenticato per l'interazione degli agenti AI con i dati operativi.