Menggunakan server MCP jarak jauh Spanner

Dokumen ini menunjukkan cara menggunakan server Model Context Protocol (MCP) jarak jauh Spanner untuk terhubung dengan aplikasi AI, termasuk Gemini CLI, ChatGPT, Claude, dan aplikasi kustom yang Anda kembangkan. Server MCP Spanner memungkinkan Anda mengakses dan menjalankan alat Spanner untuk membuat, mengelola, dan mengkueri resource Spanner dari lingkungan pengembangan yang mendukung AI dan platform agen AI. .

Server MCP jarak jauh Spanner diaktifkan saat Anda mengaktifkan Spanner API.

Model Context Protocol (MCP) menstandardisasi cara model bahasa besar (LLM) dan aplikasi atau agen AI terhubung ke sumber data eksternal. Server MCP memungkinkan Anda menggunakan alat, resource, dan perintahnya untuk melakukan tindakan dan mendapatkan data terbaru dari layanan backend-nya.

Apa perbedaan antara server MCP lokal dan jarak jauh?

Server MCP lokal
Biasanya berjalan di komputer lokal Anda dan menggunakan input dan output stream standar (stdio) untuk komunikasi antar-layanan di perangkat yang sama.
Server MCP jarak jauh
Berjalan di infrastruktur layanan dan menawarkan endpoint HTTP ke aplikasi AI untuk komunikasi antara klien MCP AI dan server MCP. Untuk mengetahui informasi selengkapnya tentang arsitektur MCP, lihat Arsitektur MCP.

Untuk mengetahui informasi tentang server MCP lokal Spanner, lihat Server MCP Spanner di GitHub.

Server MCP jarak jauh dan Google Cloud Google

Server MCP jarak jauh Google dan Google Cloud memiliki fitur dan manfaat berikut:

  • Penemuan yang disederhanakan dan terpusat
  • Endpoint HTTP global atau regional yang dikelola
  • Otorisasi terperinci
  • Keamanan perintah dan respons opsional dengan perlindungan Model Armor
  • Logging audit terpusat

Untuk mengetahui informasi tentang server MCP lainnya dan informasi tentang kontrol keamanan dan tata kelola yang tersedia untuk server MCP Google Cloud, lihat Ringkasan server MCP Google Cloud.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  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 role (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 role (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. Aktifkan Spanner API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

    Untuk project baru, Spanner API diaktifkan secara otomatis.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan server MCP Spanner, minta administrator untuk memberi Anda peran IAM berikut pada project tempat Anda ingin menggunakan server MCP Spanner:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menggunakan server MCP Spanner. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan server MCP Spanner:

  • Melakukan panggilan alat MCP: mcp.tools.call
  • Menggunakan alat MCP Spanner:
    • spanner.instances.create
    • spanner.instances.get
    • spanner.databases.create
    • spanner.databases.update
    • spanner.sessions.create
    • spanner.instanceOperations.get
    • spanner.databases.getDdl
    • spanner.databases.select
    • spanner.databases.write

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Autentikasi dan otorisasi

Server MCP Spanner menggunakan protokol OAuth 2.0 dengan Identity and Access Management (IAM) untuk autentikasi dan otorisasi. Semua Google Cloud identitas didukung untuk autentikasi ke server MCP.

Server MCP jarak jauh Spanner tidak menerima kunci API.

Sebaiknya buat identitas terpisah untuk agen menggunakan alat MCP agar akses ke resource dapat dikontrol dan dipantau. Untuk mengetahui informasi selengkapnya tentang autentikasi, lihat Mengautentikasi ke server MCP.

Cakupan OAuth MCP Spanner

OAuth 2.0 menggunakan cakupan dan kredensial untuk menentukan apakah akun utama terautentikasi diizinkan untuk melakukan tindakan tertentu pada resource. Untuk mengetahui informasi selengkapnya tentang cakupan OAuth 2.0 di Google, baca Menggunakan OAuth 2.0 untuk mengakses Google API.

Spanner memiliki cakupan OAuth alat MCP berikut:

URI cakupan untuk gcloud CLI Deskripsi
https://www.googleapis.com/auth/spanner.admin Mengizinkan akses untuk mengelola instance dan database Spanner Anda.
https://www.googleapis.com/auth/spanner.data Mengizinkan akses untuk melihat dan mengelola data di database Spanner.

Untuk mengetahui informasi selengkapnya tentang cakupan ini, lihat Spanner API.

Mengonfigurasi klien MCP untuk menggunakan server MCP Spanner

Program host, seperti Claude atau Gemini CLI, dapat membuat instance klien MCP yang terhubung ke satu server MCP. Program host dapat memiliki beberapa klien yang terhubung ke server MCP yang berbeda. Untuk terhubung ke server MCP jarak jauh, klien MCP setidaknya harus mengetahui URL server MCP jarak jauh.

Gunakan petunjuk berikut untuk mengonfigurasi klien MCP agar terhubung ke server MCP Spanner jarak jauh Anda.

Gemini CLI

Untuk menambahkan server MCP jarak jauh Spanner ke Gemini CLI Anda, konfigurasi sebagai ekstensi.

  1. Buat file ekstensi di lokasi berikut: ~/.gemini/extensions/EXT_NAME/gemini-extension.json dengan ~/ adalah direktori beranda Anda dan EXT_NAME adalah nama yang ingin Anda berikan untuk ekstensi.

  2. Tambahkan konten berikut ke file ekstensi Anda:

            {
          "name": "EXT_NAME",
          "version": "1.0.0",
          "mcpServers": {
            "Spanner MCP Server": {
              "httpUrl": "https://spanner.googleapis.com/mcp",
              "authProviderType": "google_credentials",
              "oauth": {
                "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
              },
              "timeout": 30000,
              "headers": {
                "x-goog-user-project": "PROJECT_ID"
              }
            }
          }
        }

  3. Simpan file ekstensi.

  4. Mulai Gemini CLI:

            gemini

  5. Jalankan /mcp di CLI untuk melihat server MCP yang dikonfigurasi dan alatnya.

    Responsnya mirip dengan hal berikut ini:

            Configured MCP servers:
        🟢 Spanner MCP Server (from spanner )
          - get_database_ddl
          - get_instance
          - get_operation
          - create_database
          - create_instance
          - create_session
          - commit
          - execute_sql
          - list_databases
          - list_instances

Server MCP jarak jauh siap digunakan di Gemini CLI.

Claude.ai

Anda harus memiliki paket Claude Enterprise, Pro, Max, atau Team untuk mengonfigurasi server Google dan MCP di Claude.ai. Google Cloud Untuk mengetahui informasi harga, lihat Harga Claude.

Untuk menambahkan server MCP jarak jauh Spanner ke Claude.ai, konfigurasikan konektor kustom dengan ID klien OAuth dan rahasia klien OAuth:

Buat ID dan rahasia klien OAuth 2.0

  1. Di konsol Google Cloud , buka Google Auth Platform > Clients > Create client.

    Buka Buat klien

    Anda akan diminta untuk membuat project jika belum memilih project.

  2. Pada daftar Application type, pilih Web application.

  3. Di kolom Name, masukkan nama aplikasi Anda.

  4. Di bagian URI pengalihan yang diberi otorisasi, klik + Tambahkan URI, lalu tambahkan https://claude.ai/api/mcp/auth_callback di kolom URI.

  5. Klik Create. Klien dibuat. Untuk mengakses ID klien, di konsol Google Cloud , buka Google Auth Platform > Clients.

  6. Pada daftar Client ID OAuth 2.0, pilih nama klien.

  7. Di bagian Client secrets, salin Client secret dan simpan di tempat yang aman. Anda hanya dapat menyalinnya satu kali. Jika Anda kehilangan rahasia tersebut, hapus rahasia dan buat yang baru.

Membuat konektor kustom di Claude.ai

  1. Di Claude.ai, buka setelan Konektor untuk paket Anda:

    • Untuk paket Enterprise atau Tim, buka Setelan admin > Konektor.
    • Untuk paket Pro atau Max, buka Setelan > Konektor.

  2. Klik Tambahkan konektor kustom.

  3. Dalam dialog Tambahkan konektor kustom, masukkan yang berikut:

    • Nama server: nama yang dapat dibaca manusia untuk server.
    • URL server MCP jarak jauh: https://spanner.googleapis.com/mcp

  4. Luaskan menu Setelan lanjutan, lalu masukkan hal berikut:

    • ID klien OAuth: ID klien OAuth 2.0 yang Anda buat.
    • Rahasia klien OAuth (khusus paket Pro dan Max): rahasia untuk klien OAuth 2.0 Anda. Untuk mengambil secret, buka Google Auth Platform > Clients, lalu pilih client ID OAuth yang Anda buat. Di bagian Client secrets, klik untuk menyalin Client secret.

  5. Klik Tambahkan.

    Konektor kustom dibuat.

  6. Buka menu Alat, lalu aktifkan konektor.

    Claude.ai dapat menggunakan server MCP.

ChatGPT

Anda harus memiliki langganan ChatGPT Business untuk menggunakan server MCP Google dan Spanner dengan ChatGPT.

Untuk menambahkan server MCP jarak jauh Spanner ke ChatGPT, buat ID dan secret klien Google OAuth 2.0, lalu tambahkan server MCP sebagai Aplikasi di ChatGPT.

Buat ID dan rahasia klien OAuth 2.0

  1. Di konsol Google Cloud , buka Google Auth Platform > Clients > Create client.

    Buka Buat klien

    Anda akan diminta untuk membuat project jika belum memilih project.

  2. Pada daftar Application type, pilih Web application.

  3. Di kolom Name, masukkan nama aplikasi Anda.

  4. Di bagian Authorized JavaScript origins, klik + Add URI, lalu tambahkan https://chatgpt.com di kolom URIs.

  5. Di bagian URI pengalihan yang diberi otorisasi, klik + Tambahkan URI, lalu tambahkan https://chatgpt.com/connector_platform_oauth_redirect di kolom URI.

  6. Klik Create. Klien dibuat. Untuk mengakses ID klien, di konsol Google Cloud , buka Google Auth Platform > Clients.

  7. Pada daftar Client ID OAuth 2.0, pilih nama klien.

  8. Di bagian Client secrets, salin Client secret dan simpan di tempat yang aman. Anda hanya dapat menyalinnya satu kali. Jika Anda kehilangan rahasia tersebut, hapus rahasia dan buat yang baru.

Menambahkan server MCP sebagai aplikasi di ChatGPT

  1. Login ke ChatGPT.
  2. Aktifkan Mode developer:
    1. Di ChatGPT, klik nama pengguna Anda untuk membuka Menu profil, lalu pilih Setelan.
    2. Di menu Setelan, pilih Aplikasi, lalu klik Setelan lanjutan.
    3. Di Setelan lanjutan, klik tombol Mode developer ke posisi aktif.
  3. Di Setelan > Aplikasi, klik tombol Buat aplikasi.
  4. Pada dialog Aplikasi baru, masukkan informasi berikut:
    • Name: nama server MCP.
    • Deskripsi: deskripsi opsional server MCP.
    • URL server MCP: https://spanner.googleapis.com/mcp
    • Autentikasi:
      • Di menu Authentication, pilih OAuth.
      • Di kolom OAuth client ID, masukkan client ID Google OAuth Anda.
      • Di kolom OAuth secret, masukkan rahasia klien Google OAuth Anda.
    • Konfirmasi bahwa Anda memahami risiko yang terkait dengan penggunaan server MCP, lalu klik Create.

Server MCP ditampilkan di menu Apps, dan siap digunakan melalui perintah chat.

Panduan umum untuk klien MCP

Jika petunjuk khusus untuk klien MCP Anda tidak disertakan dalam Mengonfigurasi klien MCP untuk menggunakan server MCP Spanner, gunakan informasi berikut untuk terhubung ke server MCP jarak jauh di program host atau aplikasi AI Anda. Anda akan diminta untuk memasukkan detail tentang server, seperti nama dan URL-nya.

Untuk server MCP jarak jauh Spanner, masukkan informasi berikut:

  • Nama server: Server MCP Spanner
  • URL Server atau Endpoint: https://spanner.googleapis.com/mcp
  • Transportasi: HTTP
  • Detail autentikasi: Bergantung pada cara autentikasi yang Anda inginkan, Anda dapat memasukkan Google Cloud kredensial, ID Klien OAuth dan rahasia, atau identitas dan kredensial agen.

Untuk panduan umum lainnya, lihat referensi berikut:

Alat yang tersedia

Untuk melihat detail alat MCP yang tersedia dan deskripsinya untuk server MCP Spanner, lihat referensi MCP Spanner.

Alat daftar

Gunakan pemeriksa MCP untuk mencantumkan alat, atau kirim permintaan HTTP tools/list langsung ke server MCP jarak jauh Spanner. Metode tools/list tidak memerlukan autentikasi.

POST /mcp HTTP/1.1
Host: spanner.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

Kemampuan observasi

Server MCP Spanner mendukung alat observasi dan introspeksi Spanner.

Meminta Tag

Kueri yang dijalankan atau transaksi yang dilakukan menggunakan server MCP Spanner ditandai secara otomatis dengan tag permintaan tertentu. Anda dapat menggunakan tag ini untuk men-debug kueri dan transaksi. Untuk mengetahui informasi selengkapnya, lihat Memecahkan masalah dengan tag permintaan dan tag transaksi.

Nama alat Tag permintaan
execute_sql mcp_execute_sql
execute_sql_readonly mcp_execute_sql_readonly
commit mcp_commit

Kasus penggunaan sampel

Berikut adalah contoh kasus penggunaan untuk server MCP Spanner.

Pengembangan aplikasi dengan Spanner

Developer aplikasi dapat menggunakan server MCP Spanner untuk menyediakan resource, membuat database, dan mengisi data contoh.

Contoh perintah: "Buat instance Spanner regional di project PROJECT_ID dalam konfigurasi instance regional us-central1. Buat database untuk melacak inventaris dan isi 5 produk sampel."

Ganti PROJECT_ID dengan Google Cloud project ID Anda.

Alur kerja:

Alur kerja untuk mengembangkan aplikasi mungkin terlihat seperti berikut:

  • Agen memanggil alat create_instance untuk menyediakan instance Spanner baru menggunakan konfigurasi instance yang ditentukan. Agen dapat memanggil alat get_operation untuk memverifikasi apakah instance siap digunakan.

  • Agen memanggil alat create_database untuk membuat database baru dengan skema yang diperlukan. Agen dapat memanggil alat get_operation untuk memeriksa status operasi pembuatan database.

  • Agen dapat menggunakan kombinasi alat create_session, execute_sql, dan commit untuk menyisipkan data sampel.

  • Secara opsional, agen dapat memanggil alat execute_sql untuk membuat kueri dan memvalidasi pembuatan data sampel.

Insight operasional dan pengelolaan konfigurasi database

Administrator Spanner dapat menggunakan server MCP Spanner untuk mengumpulkan informasi tentang instance dan database Spanner menggunakan alat seperti list_instances, get_instance, list_databases, dan get_database_ddl.

Contoh perintah:

  • "List all Spanner instances in the current project." (Mencantumkan semua instance Spanner dalam project saat ini).
  • "Cantumkan semua database di instance Spanner saat ini."
  • "Show the schema for the current Spanner database." (Tampilkan skema untuk database Spanner saat ini.)

Konfigurasi keamanan dan keselamatan opsional

MCP memperkenalkan risiko dan pertimbangan keamanan baru karena berbagai tindakan yang dapat Anda lakukan dengan alat MCP. Untuk meminimalkan dan mengelola risiko ini,Google Cloud menawarkan setelan default dan kebijakan yang dapat disesuaikan untuk mengontrol penggunaan alat MCP di organisasi atau project Google CloudAnda.

Untuk mengetahui informasi selengkapnya tentang keamanan dan tata kelola MCP, lihat Keamanan dan keselamatan AI.

Menggunakan Model Armor

Model Armor adalah layanan Google Cloud yang dirancang untuk meningkatkan keamanan dan keselamatan aplikasi AI Anda. Model Armor bekerja dengan menyaring perintah dan respons LLM secara proaktif, melindungi dari berbagai risiko, dan mendukung praktik AI yang bertanggung jawab. Baik Anda men-deploy AI di lingkungan cloud Anda, atau di penyedia cloud eksternal, Model Armor dapat membantu Anda mencegah input berbahaya, memverifikasi keamanan konten, melindungi data sensitif, menjaga kepatuhan, dan menerapkan kebijakan keamanan dan keselamatan AI Anda secara konsisten di seluruh lanskap AI Anda yang beragam.

Jika Model Armor diaktifkan dengan logging diaktifkan, Model Armor akan mencatat seluruh payload. Hal ini dapat mengekspos informasi sensitif dalam log Anda.

Mengaktifkan Model Armor

Anda harus mengaktifkan Model Armor API sebelum dapat menggunakan Model Armor.

Konsol

  1. Aktifkan Model Armor API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  2. Pilih project tempat Anda ingin mengaktifkan Model Armor.

gcloud

Sebelum memulai, ikuti langkah-langkah berikut menggunakan Google Cloud CLI dengan Model Armor API:

  1. Di konsol Google Cloud , aktifkan Cloud Shell.

    Aktifkan Cloud Shell

    Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

  2. Jalankan perintah berikut untuk menetapkan endpoint API bagi layanan Model Armor.

    gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

    Ganti LOCATION dengan region tempat Anda ingin menggunakan Model Armor.

Mengonfigurasi perlindungan untuk server MCP jarak jauh dan Google Cloud Google

Untuk membantu melindungi panggilan dan respons alat MCP, Anda dapat menggunakan setelan batas bawah Model Armor. Setelan minimum menentukan filter keamanan minimum yang berlaku di seluruh project. Konfigurasi ini menerapkan serangkaian filter yang konsisten ke semua panggilan dan respons alat MCP dalam project.

Siapkan setelan minimum Model Armor dengan pengamanan MCP diaktifkan. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi setelan batas bawah Model Armor.

Lihat contoh perintah berikut:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Perhatikan setelan berikut:

  • INSPECT_AND_BLOCK: Jenis penegakan yang memeriksa konten untuk server MCP Google dan memblokir perintah dan respons yang cocok dengan filter.
  • ENABLED: Setelan yang mengaktifkan filter atau penerapan.
  • MEDIUM_AND_ABOVE: Tingkat keyakinan untuk setelan filter Responsible AI - Berbahaya. Anda dapat mengubah setelan ini, meskipun nilai yang lebih rendah dapat menghasilkan lebih banyak positif palsu. Untuk mengetahui informasi selengkapnya, lihat Tingkat keyakinan Model Armor.

Menonaktifkan pemindaian traffic MCP dengan Model Armor

Untuk menghentikan Model Armor memindai traffic secara otomatis ke dan dari server MCP Google berdasarkan setelan batas bawah project, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

Ganti PROJECT_ID dengan ID project Google Cloud . Model Armor tidak otomatis menerapkan aturan yang ditentukan dalam setelan batas bawah project ini ke traffic server MCP Google.

Setelan minimum Model Armor dan konfigurasi umum dapat memengaruhi lebih dari sekadar MCP. Karena Model Armor terintegrasi dengan layanan seperti Platform Agen, setiap perubahan yang Anda lakukan pada setelan batas bawah dapat memengaruhi pemindaian traffic dan perilaku keamanan di semua layanan terintegrasi, bukan hanya MCP.

Mengontrol penggunaan MCP dengan kebijakan penolakan IAM

Kebijakan penolakan Identity and Access Management (IAM) membantu Anda mengamankan server MCP jarak jauh Google Cloud . Konfigurasi kebijakan ini untuk memblokir akses alat MCP yang tidak diinginkan.

Misalnya, Anda dapat menolak atau mengizinkan akses berdasarkan:

  • Kepala sekolah
  • Properti alat seperti hanya baca
  • Client ID OAuth aplikasi

Untuk mengetahui informasi selengkapnya, lihat Mengontrol penggunaan MCP dengan Identity and Access Management.

Langkah berikutnya