Codelab: Server MCP Spanner

1. Ringkasan

Codelab ini menunjukkan cara mengeluarkan kueri grafik di Spanner menggunakan gemini-cli dan server Model Context Protocol (MCP) Google. Dengan mengintegrasikan database multimodel Spanner, termasuk Spanner Graph, dengan layanan MCP terkelola, Anda dapat menggunakan bahasa alami untuk mengungkap hubungan tersembunyi dalam data Anda—seperti lingkaran penipuan atau dependensi rantai pasokan—dalam satu database tanpa menulis kueri GQL (Graph Query Language) atau SQL yang rumit secara manual.

Yang akan Anda pelajari

Cara menyiapkan database multi-model Spanner termasuk Spanner Graph untuk MCP.
Cara menghubungkan Gemini CLI ke endpoint layanan Spanner jarak jauh terkelola.
Cara menggunakan bahasa alami untuk membuat SQL yang terintegrasi dengan GQL secara otomatis untuk melakukan penelusuran grafik dan pencocokan pola bersama dengan operasi relasional.
Praktik terbaik untuk mengamankan data grafik dalam alur kerja AI.

Prasyarat

Project Google Cloud yang mengaktifkan penagihan.
Akses ke terminal (seperti Cloud Shell). Lihat codelab ini.
CLI gcloud diinstal dan diautentikasi.
Akses ke Gemini CLI.

CATATAN: Anda akan menjalankan semua perintah di terminal Unix. Lihat prasyarat di atas untuk mendapatkan akses ke terminal dengan akses ke gcloud dengan autentikasi yang tepat.

2. Menyiapkan Lingkungan Multi-model Spanner

MCP terkelola berfungsi paling baik jika skema database telah ditentukan sebelumnya. Kita akan membuat grafik "Deteksi Penipuan" keuangan berdasarkan sampel Spanner Graph.

Mengaktifkan 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}

Membuat Skema Database

Buat instance dan database dengan tabel database dan grafik properti. Skema ini melacak Akun, Orang, dan Transfer di antara keduanya.

CATATAN: Anda dapat menjalankan pernyataan DDL ini dari Spanner Studio. Lihat link ini untuk mengetahui info tentang cara membuat dan membuat kueri database Spanner dari konsol 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)
  );

Mengisi data

Sisipkan Orang

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');

Menyisipkan Akun

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');

Menautkan Orang ke Akun

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');

Menambahkan Transfer

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. Mengonfigurasi Gemini CLI dan Spanner MCP

Lab ini dirancang untuk menggunakan Gemini CLI sebagai agen utama untuk melakukan sebagian besar tindakan dan langkah pertama adalah mengonfigurasinya agar dapat bekerja dengan server MCP Spanner jarak jauh. Sebaiknya gunakan juga Gemini CLI versi terbaru dan Gemini versi terbaru seperti Gemini-3-pro atau Gemini-3-flash (saat ini dalam pratinjau).

Jika Anda sudah memiliki Gemini CLI versi terbaru dan mengonfigurasinya untuk menggunakan model Gemini terbaru, Anda dapat melewati 2 langkah berikutnya dan langsung ke langkah 3.

Mendapatkan Kunci Gemini API

Untuk menggunakan model Gemini terbaru di Gemini CLI, Anda harus mengonfigurasinya dengan autentikasi kunci API. Kita bisa mendapatkan kunci API di Google AI Studio

Buka Google AI Studio -> Get API key di browser Anda.
Di sisi kanan layar, klik tombol Create API key
Di jendela pop-up, pilih project Anda atau impor jika tidak terlihat di sana

Buat kunci API.
Anda dapat menyalin kunci menggunakan tombol salin di sisi kanan.

Kunci sudah disiapkan dan sekarang kita dapat menggunakannya untuk Gemini CLI

Mengonfigurasi Gemini CLI

Gemini CLI dapat dikonfigurasi melalui file konfigurasi setelan atau secara interaktif menggunakan perintah /settings. Kita ingin setelan kita dipertahankan dalam file setelan.

Pertama, kita akan membuat direktori untuk project. Mari kita sebut direktori tersebut projectspannermcp dan beralih ke direktori tersebut menggunakan perintah berikut.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

Di direktori, kita akan membuat direktori untuk file konfigurasi Gemini dan akan menjalankan semua perintah. Secara default, Gemini CLI menggunakan file konfigurasi cakupan pengguna dan ekstensi yang diinstal di direktori ~/.gemini. Namun, kita akan membuat konfigurasi cakupan project kita sendiri di direktori ~/projectspannermcp. Mulai dengan membuat direktori dan file konfigurasi.

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

Kemudian, kita akan membuka file ~/projectspannermcp/.gemini/settings.json menggunakan editor Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

Di jendela editor yang terbuka, tambahkan konfigurasi berikut.

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

Setelah mengedit file, Anda dapat menggunakan ctrl+s untuk menyimpan perubahan dan beralih kembali ke terminal dengan mengklik tombol Open Terminal

File settings.json di atas menetapkan jenis autentikasi Gemini CLI Anda sebagai gemini-api-key dan Anda perlu memberikan kunci ke model. Anda dapat melakukannya dengan membuat file .env di direktori tempat Anda ingin menggunakan Gemini CLI dan menyimpan kunci API untuk autentikasi Gemini CLI sebagai variabel lingkungan yang akan diambil saat Anda memulai IDE.

Mari kita edit file menggunakan editor Cloud Shell

edit ~/projectspannermcp/.env

Simpan kunci API yang Anda buat di langkah "Dapatkan Kunci API Gemini" di atas.

GEMINI_API_KEY= <YOUR_API_KEY>

Sekarang Anda dapat kembali ke terminal dan melanjutkan. Langkah berikutnya adalah mengupdate Gemini CLI ke versi terbaru. Versi di Google Cloud Shell atau di lingkungan Anda mungkin sudah tidak berlaku dan mungkin tidak berfungsi dengan benar dengan konfigurasi dan layanan MCP terbaru. Jadi, Anda harus mengupdate Gemini CLI ke versi terbaru dan memulainya. Di terminal, jalankan perintah berikut.

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

Sekarang Anda dapat memverifikasi versi. Perlu diingat bahwa jika Anda bekerja di Google Cloud Shell, setiap kali Anda memulai ulang shell, shell tersebut mungkin akan kembali ke versi sebelumnya. Perubahan yang Anda buat pada Gemini CLI itu sendiri tidak bersifat permanen di Cloud Shell.

gemini --version

Perintah ini akan menampilkan versi Gemini CLI terbaru (versi 0.27 pada saat penulisan lab ini). Anda dapat memverifikasi versi Gemini CLI terbaru di sini. Sekarang kita dapat memulainya dan memastikan bahwa Gemini menggunakan model Gemini terbaru. Jalankan perintah berikut di folder project Anda untuk memulai Gemini CLI.

gemini

Saat Gemini CLI dimulai, Anda dapat memeriksa versi dan model dengan menjalankan perintah /about di antarmuka. Anda akan mendapatkan sesuatu seperti gambar di bawah.

Anda dapat melihat bahwa model ini menggunakan model Gemini-3 terbaru. Langkah-langkah di bawah yang menunjukkan kueri bahasa alami memerlukan penggunaan model Gemini-3.

Mengonfigurasi Gemini CLI untuk menggunakan Spanner MCP

Kita memiliki satu hal lagi yang perlu ditambahkan ke file settings.json. Pertama, keluar dari gemini cli (Anda dapat menekan Ctrl+C dua kali).

Di settings.json yang sama seperti di atas, kita akan menambahkan bit untuk mengonfigurasi server MCP Spanner. Kami telah menyertakan settings.json lengkap di bawah. Perhatikan bit yang dimulai dengan "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"
   ]
 }
}

Sebelum melanjutkan ke langkah berikutnya, lakukan autentikasi

gcloud auth application-default login

Setelah autentikasi, mulai gemini-cli lagi

gemini

4. Membuat Multi-model termasuk Kueri Berfokus pada Grafik

Mari kita mulai dengan mencantumkan instance Spanner di project yang dikonfigurasi.

"Please list all Spanner instances in my project <project1> (replace with your project id)" (Cantumkan semua instance Spanner di project <project1> saya (ganti dengan project id Anda))

Respons:

The Spanner instances in your project are:
 [instance1]

"Please list all databases in <instance1> (replace with your instance)" (Cantumkan semua database di <instance1> (ganti dengan instance Anda))

Respons:

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

Selanjutnya, beri tahu Gemini untuk mengingat instance/database tempat Anda menjalankan pernyataan DDL dan pernyataan penyisipan di bagian penyiapan Spanner:

"Asumsikan bahwa semua kueri akan dikirimkan terhadap db <your-db> di instance <your-instance> kecuali dinyatakan lain"

NOTE: Gunakan instance/database yang digunakan untuk menjalankan pernyataan DDL dan pernyataan penyisipan di atas.

Setelah terhubung, model Gemini akan memahami skema grafik. Anda kini dapat menjalankan penelusuran yang canggih menggunakan bahasa alami.

Model akan menerjemahkannya ke GQL (Graph Query Language) secara otomatis:

Mengidentifikasi Struktur Jaringan

"Jelaskan struktur grafik properti 'FinGraph'. Apa label node dan edge?"

Respons:

  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

Deteksi Penipuan & Siklus

"Temukan transfer melingkar yang mengirimkan uang dari Akun A dan akhirnya dikembalikan ke Akun A dalam 3 hop."

Respons:

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.

Analisis Hubungan Mendalam

"Identifikasi semua Orang yang memiliki akun yang telah mengirimkan lebih dari $499 ke akun yang dimiliki oleh orang yang berbeda dalam 24 bulan terakhir."

Respons:

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

Pencarian Jalur

"Temukan jalur transfer terpendek antara ID Akun 16 dan ID Akun 20."

Respons:

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. Selamat!

Selamat, Anda telah menyelesaikan codelab.

Yang telah kita bahas

Dalam codelab ini, Anda telah mempelajari cara mengonfigurasi gemini-cli dengan server MCP Spanner dan mengeluarkan kueri bahasa alami terhadap data Spanner Graph untuk menampilkan insight. Berikut ringkasan pencapaian pentingnya:

Infrastruktur Terkelola: Mengaktifkan server MCP Spanner jarak jauh, sehingga tidak memerlukan proxy lokal atau MCP Toolbox.
Integrasi Grafik: Mengonfigurasi Spanner Property Graph (FinGraph) dengan Node dan Edge untuk merepresentasikan hubungan yang kompleks.
Alat Bawaan: Menghubungkan Gemini CLI langsung ke endpoint Spanner terkelola menggunakan skema URI standar.
SQL & GQL Bahasa Natural: Menggunakan server dengan perintah khusus grafik, sehingga LLM dapat melakukan penelusuran multi-hop dan deteksi siklus tanpa coding SQL/GQL manual.
Kesiapan Perusahaan: Menjelaskan bagaimana MCP terkelola menyediakan jalur yang skalabel dan diautentikasi bagi agen AI untuk berinteraksi dengan data operasional.