Pelajari cara menggunakan server MCP BigQuery Migration Service

Dokumen ini menunjukkan cara menggunakan server Model Context Protocol (MCP) jarak jauh BigQuery untuk terhubung dengan aplikasi AI, termasuk Gemini CLI, ChatGPT, Claude, dan aplikasi kustom yang Anda kembangkan. Anda dapat menggunakan server Model Context Protocol (MCP) BigQuery Migration Service untuk melakukan tugas seperti menerjemahkan kueri SQL ke dalam sintaksis GoogleSQL, membuat pernyataan DDL dari kueri input SQL, dan mendapatkan penjelasan terjemahan SQL.

Server MCP jarak jauh BigQuery diaktifkan saat Anda mengaktifkan BigQuery 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.

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 berjalan di infrastruktur layanan dan menawarkan endpoint HTTPS ke aplikasi AI untuk komunikasi antara klien MCP AI dan server MCP. Untuk mengetahui informasi selengkapnya tentang arsitektur MCP, lihat Arsitektur MCP.

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

  • Penemuan yang disederhanakan dan terpusat
  • Endpoint HTTPS 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. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  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. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  6. Aktifkan BigQuery Migration Service 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

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengaktifkan server MCP BigQuery Migration Service, minta administrator Anda untuk memberi Anda peran IAM berikut pada project tempat Anda ingin mengaktifkan server MCP BigQuery Migration Service:

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

Peran bawaan ini berisi izin yang diperlukan untuk mengaktifkan server MCP BigQuery Migration Service. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengaktifkan server MCP BigQuery Migration Service:

  • Lakukan panggilan alat MCP: mcp.tools.call
  • Menggunakan BigQuery Migration Service:
    • bigquerymigration.workflows.create
    • bigquerymigration.workflows.get
    • bigquerymigration.workflows.list
    • bigquerymigration.workflows.delete
    • bigquerymigration.subtasks.get
    • bigquerymigration.subtasks.list

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

Izin BigQuery Migration Service tambahan mungkin diperlukan, bergantung pada tugasnya. Untuk mengetahui informasi tentang peran dan izin BigQuery Migration Service, lihat Peran dan izin BigQuery Migration Service.

Autentikasi dan otorisasi

Server MCP BigQuery Migration Service 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 BigQuery Migration Service tidak menerima kunci API.

Cakupan OAuth MCP BigQuery Migration Service

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, lihat Menggunakan OAuth 2.0 untuk mengakses Google API.

BigQuery Migration Service memiliki cakupan OAuth alat MCP berikut:

URI cakupan untuk gcloud CLI Deskripsi
https://www.googleapis.com/auth/bigquerymigration Melihat dan mengelola alur kerja Anda di BigQuery Migration Service serta melihat alamat email untuk Akun Google Anda.
https://www.googleapis.com/auth/devstorage.read_only Cakupan ini diperlukan untuk terjemahan kueri yang membaca data dari Cloud Storage.

Resource yang diakses selama panggilan alat mungkin memerlukan cakupan tambahan.

Mengonfigurasi klien MCP untuk menggunakan server MCP BigQuery Migration Service

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, klien MCP harus mengetahui setidaknya URL server MCP.

Di host Anda, cari cara untuk terhubung ke server MCP. Anda akan diminta untuk memasukkan detail tentang server, seperti nama dan URL-nya.

Untuk server MCP BigQuery Migration Service, masukkan hal berikut sesuai kebutuhan:

  • Nama server: Server MCP BigQuery Migration Service
  • URL Server atau Endpoint: bigquerymigration.googleapis.com/mcp
  • Transportasi: HTTP

  • Detail autentikasi: kredensial Anda, ID Klien dan rahasia OAuth Anda, atau identitas dan kredensial agen Google Cloud

    Detail autentikasi yang Anda pilih bergantung pada cara Anda ingin mengautentikasi. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi ke server MCP.

Untuk panduan khusus host, lihat artikel berikut:

Untuk panduan yang lebih umum, lihat Menghubungkan ke server MCP jarak jauh.

Alat yang tersedia

Untuk melihat detail alat MCP yang tersedia dan deskripsinya untuk server MCP BigQuery Migration Service, lihat referensi MCP BigQuery Migration Service.

Alat daftar

Gunakan pemeriksa MCP untuk mencantumkan alat, atau kirim permintaan HTTP tools/list langsung ke server MCP BigQuery Migration Service. Metode tools/list tidak memerlukan autentikasi.

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

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

Kasus penggunaan sampel

Berikut adalah contoh kasus penggunaan untuk server MCP BigQuery Migration Service:

  • Dengan menggunakan klien MCP dengan IDE, terjemahkan file kueri ke dalam sintaksis GoogleSQL.
  • Menggunakan klien MCP tanpa IDE, terjemahkan kueri tertentu ke dalam sintaksis GoogleSQL.
  • Menilai kualitas terjemahan.
  • Mendapatkan penjelasan terjemahan SQL.
  • Buat pernyataan DDL untuk kueri tertentu.

Contoh perintah

Anda dapat menggunakan perintah contoh berikut untuk membuat dan mengelola resource BigQuery Migration Service:

  • Terjemahkan kueri DIALECT dalam FILENAME ini. Gunakan PROJECT_ID dan LOCATION. Mempertahankan output dan log terjemahan ke dalam direktori terpisah.

    Saat Anda menggunakan perintah ini, klien MCP akan memanggil alat translate_query untuk menerjemahkan kueri dalam file yang ditentukan. Klien MCP memanggil alat get_translation secara berkala untuk mendapatkan hasilnya. Setelah terjemahan selesai, klien akan menulis output ke direktori output dan log ke direktori log.

  • Terjemahkan kueri ini dari DIALECT: QUERY. Gunakan PROJECT_ID dan LOCATION.

    Saat Anda menggunakan perintah ini, klien MCP akan memanggil alat translate_query untuk menerjemahkan kueri yang ditentukan dan menampilkan hasil terjemahan.

  • Menilai kualitas terjemahan.

    Saat Anda menggunakan perintah ini, klien MCP akan membaca dan memeriksa log terjemahan serta menampilkan ringkasan masalah terjemahan dengan saran langkah berikutnya.

  • Jelaskan terjemahannya.

    Saat Anda menggunakan perintah ini, klien MCP memanggil alat explain_translation untuk mendapatkan penjelasan terjemahan. Jika log terjemahan berisi error RelationNotFound atau AttributeNotFound, klien MCP akan menyarankan Anda untuk membuat paket metadata. Jika tidak dapat membuat metadata, Anda dapat mengirim perintah yang meminta pernyataan DDL.

    Contoh responsnya akan terlihat seperti berikut:

    The translated code converts Teradata-specific features into their
BigQuery equivalents. Here's a breakdown of the key changes:
* `MACRO` to `PROCEDURE`: The `YourMacroName` macro was converted
into a BigQuery stored procedure because
BigQuery doesn't support macros.
* `SELECT INTO` to `SET`:
  * For setting multiple `OUT` parameters in `YourStoredProcedureName`, the
    `SELECT ... INTO` is changed to `SET (...) = (SELECT STRUCT(...))`.
  * For single variable assignment in `YourOtherProcedureName`,
    `SELECT ... INTO` is replaced by `SET variable = (SELECT ...)` which is
    the standard in BigQuery.
* Atomic Operations to `MERGE: The BEGIN REQUEST ... END REQUEST` blocks in
  the `ProcedureA`, `ProcedureB`, and `ProcedureC` procedures,
  which perform atomic "update or insert" operations, are translated into
  standard SQL `MERGE` statements. This is the correct and modern way to
  handle this logic in BigQuery.

  • Buat DDL untuk kueri input ini.

    Klien MCP memanggil alat generate_ddl_suggestion untuk memulai tugas saran. Klien mendapatkan hasil saran dengan memanggil alat fetch_ddl_suggestion. Jika saran tersedia, klien MCP akan menampilkannya.

    Jika pernyataan DDL sudah benar, Anda dapat mengirimkan perintah untuk menambahkan pernyataan DDL yang dihasilkan ke kueri guna meningkatkan kualitas terjemahan.

  • Tambahkan pernyataan DDL yang dihasilkan ke kueri input dan terjemahkan ulang.

    Saat Anda menggunakan perintah ini, klien MCP akan menambahkan pernyataan DDL ke kueri input asli dan memanggil alat translate_query. Klien memanggil alat get_translation untuk mendapatkan terjemahan. Terjemahan kueri baru dan log tetap ada saat tersedia.

    Jika pernyataan DDL yang dihasilkan sudah benar, error RelationNotFound atau AttributeNotFound akan diselesaikan sehingga kualitas terjemahan meningkat.

Dalam perintah, ganti kode berikut:

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 kebijakan default dan yang dapat disesuaikan untuk mengontrol penggunaan alat MCP di organisasi atau project Anda. Google Cloud

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.

Model Armor hanya tersedia di lokasi regional tertentu. Jika Model Armor diaktifkan untuk project, dan panggilan ke project tersebut berasal dari wilayah yang tidak didukung, Model Armor tidak akan dipanggil dan konten tidak akan dipindai oleh Model Armor. Untuk mengetahui informasi selengkapnya, lihat Lokasi Model Armor.

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

Jika Anda ingin berhenti memindai traffic MCP Google dengan Model Armor, 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 akan memindai traffic MCP dalam project.

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.

Kuota dan batas

Server MCP BigQuery Migration Service tidak memiliki kuota sendiri. Tidak ada batasan jumlah panggilan yang dapat Anda lakukan ke server MCP.

Anda tetap tunduk pada kuota yang diterapkan oleh API yang dipanggil oleh alat server MCP. Untuk mengetahui informasi selengkapnya, lihat BigQuery Migration Service API di halaman Kuota dan batas.

Langkah berikutnya