Menghubungkan ke agen data menggunakan MCP

Sebagai administrator platform agentic pihak ketiga (seperti Claude Code, Claude Cowork, atau ChatGPT) atau yang dikelola Google (seperti Gemini Enterprise), Anda dapat mengonfigurasi koneksi Model Context Protocol (MCP) kustom ke server MCP jarak jauh Analisis Percakapan API (https://geminidataanalytics.googleapis.com/mcp). Dengan menghubungkan platform agentic ke server ini, agen root platform Anda dapat menemukan dan membuat kueri agen data khusus atas nama pengguna bisnis.

Server MCP jarak jauh Analisis Percakapan API menggunakan alur OAuth 2.0 3-legged untuk menyebarkan kredensial pengguna akhir (EUC) ke BigQuery. Penyebaran ini memastikan bahwa permintaan penemuan agen dan kueri BigQuery berjalan di bawah identitas pengguna yang diautentikasi dan mematuhi izin Identity and Access Management (IAM) serta kebijakan tata kelola data yang ada. Agen data yang didukung Looker tidak menerima kredensial pengguna akhir; sebagai gantinya, kueri memerlukan kredensial klien Looker API yang terpisah (lihat Autentikasi untuk agen data yang didukung Looker).

Untuk ringkasan arsitektur tentang cara agen root — agen pengatur utama yang menerima permintaan pengguna — berkomunikasi dengan server MCP jarak jauh, lihat Server MCP jarak jauh Analisis Percakapan API.

Sebelum memulai

Sebelum mengonfigurasi koneksi MCP di platform agentic Anda, selesaikan prasyarat berikut:

  1. Di project Google Cloud , aktifkan API yang diperlukan untuk Conversational Analytics API dan BigQuery.
  2. Pastikan operator data telah membuat dan mengonfigurasi satu atau beberapa agen data di project Google Cloud Anda, termasuk deskripsi yang jelas tentang sumber data yang dapat diakses oleh setiap agen dan pertanyaan yang dapat dijawabnya.
  3. Pastikan pengguna bisnis yang akan melakukan autentikasi melalui koneksi MCP memiliki peran IAM yang diperlukan dan akses baca ke set data target serta akses ke agen.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk melakukan autentikasi melalui server MCP jarak jauh dan mengkueri agen data, minta administrator untuk memberi Anda peran IAM berikut:

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

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengonfigurasi kredensial dan cakupan OAuth 2.0

Agar platform agen Anda dapat mengautentikasi pengguna dan meneruskan kredensial mereka ke server MCP jarak jauh Conversational Analytics API, Anda harus membuat kredensial OAuth 2.0 (client ID dan rahasia klien) di project Google Cloud Anda.

Ikuti langkah-langkah standar di Menggunakan OAuth 2.0 untuk Mengakses Google API guna mengonfigurasi layar izin OAuth dan membuat client ID OAuth 2.0 di halaman Kredensial konsolGoogle Cloud . Saat mengonfigurasi kredensial Anda, terapkan setelan berikut yang khusus untuk integrasi MCP Analisis Percakapan API:

  1. Audience: Jika organisasi Anda menggunakan Google Workspace, pilih Internal. Pilihan ini membatasi akses ke pengguna dalam organisasi Anda, menghindari perlunya verifikasi aplikasi OAuth untuk cakupan sensitif, dan memastikan bahwa kebijakan Kontrol Akses Aplikasi Google Workspace tidak memblokir pengguna untuk melakukan autentikasi.
  2. Jenis aplikasi dan URI pengalihan: Pilih Aplikasi web sebagai jenis aplikasi, dan tambahkan URI pengalihan yang diizinkan yang diperlukan oleh platform agen Anda (misalnya, https://vertexaisearch.cloud.google.com/oauth-redirect saat mengonfigurasi konektor MCP kustom di Gemini Enterprise).
  3. Cakupan OAuth: Konfigurasikan layar izin OAuth dan klien Anda untuk meminta kedua cakupan berikut agar agen root memiliki izin untuk memanggil alat Analisis Percakapan API dan menjalankan kueri BigQuery hanya baca atas nama pengguna:
    • Cakupan Analisis Data Gemini: https://www.googleapis.com/auth/geminidataanalytics
    • Cakupan hanya baca BigQuery: https://www.googleapis.com/auth/bigquery.readonly
  4. Salin dan simpan dengan aman Client ID dan Client Secret yang dihasilkan.

Mengonfigurasi koneksi MCP kustom

Setelah membuat client ID dan rahasia klien OAuth 2.0, daftarkan koneksi MCP kustom (atau konektor MCP kustom) di setelan administrasi platform agentic Anda:

  1. Di platform agentic Anda, buat koneksi server MCP kustom baru dan tentukan nilai konfigurasi berikut:

    Setelan Nilai
    URL server MCP https://geminidataanalytics.googleapis.com/mcp
    Metode autentikasi OAuth 2.0
    URL Otorisasi https://accounts.google.com/o/oauth2/v2/auth
    Parameter URL otorisasi

    &access_type=offline&prompt=consent

    Gunakan string parameter ini jika platform Anda memerlukan token refresh offline untuk sesi pengguna.
    URL Token https://oauth2.googleapis.com/token
    Cakupan

    https://www.googleapis.com/auth/geminidataanalytics

    https://www.googleapis.com/auth/bigquery.readonly

    Jika platform Anda mengharapkan satu string yang dipisahkan spasi, masukkan:

    https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly
    Client ID CLIENT_ID (client ID OAuth 2.0 yang Anda buat di bagian sebelumnya)
    Rahasia Klien CLIENT_SECRET (rahasia klien OAuth 2.0 yang Anda buat di bagian sebelumnya)

  2. Verifikasi koneksi OAuth di platform Anda jika diminta. Saat layar izin Google terbuka, login dan konfirmasi bahwa aplikasi meminta akses hanya baca Gemini Data Analytics dan BigQuery.

  3. Sinkronkan atau muat ulang alat (tindakan) untuk koneksi MCP di platform Anda agar klien MCP memanggil tools/list di https://geminidataanalytics.googleapis.com/mcp untuk mengimpor skema alat (seperti list_data_agents, get_data_agent, dan chat), dan pastikan alat yang diimpor diaktifkan.

Mengonfigurasi petunjuk perintah untuk agen root

Alat MCP Conversational Analytics API—list_data_agents, get_data_agent, dan chat—memerlukan project ID dan lokasi Google Cloud target (misalnya, projects/PROJECT_ID/locations/LOCATION). Karena pengguna bisnis biasanya tidak mengetahui project ID Google Cloud mana yang menghosting agen data organisasi Anda, berikan project ID dan lokasi target dalam petunjuk sistem kustom atau konfigurasi keterampilan agen root Anda. Hal ini mencegah agen root meminta pengguna bisnis untuk memberikan project ID saat mereka mengajukan pertanyaan data.

Menambahkan petunjuk sistem untuk penemuan dan perutean agen

Tambahkan petunjuk berikut ke perintah sistem atau petunjuk kustom agen root Anda, dengan mengganti PROJECT_ID dengan project ID Google CloudAnda dan LOCATION dengan lokasi resource Anda (seperti global, us, atau eu):

When answering questions about enterprise data using the Conversational
Analytics MCP tools, always use the Google Cloud project ID
"PROJECT_ID" and location "LOCATION" (resource path
"projects/PROJECT_ID/locations/LOCATION"). Do not ask the user to
provide a Google Cloud project ID or location.

To answer a user's data question:
1. Call list_data_agents for "projects/PROJECT_ID/locations/LOCATION"
   to discover the available data agents and review their descriptions.
2. If you need additional context about a candidate agent's connected tables or
   verified queries, call get_data_agent for that agent.
3. Call the chat tool passing parent ("projects/PROJECT_ID/locations/LOCATION"),
   dataAgentContext with the full agent resource name
   ("projects/PROJECT_ID/locations/LOCATION/dataAgents/<var>AGENT_ID</var>"),
   and the user's question in messages.

Autentikasi untuk agen data yang didukung Looker

Jika agen data Anda terhubung ke Looker Explore, permintaan ke alat chat harus menyertakan blok credentials yang berisi kredensial Looker API (client ID dan rahasia klien), karena Looker mengelola autentikasi secara independen dari IAM.

Saat mengonfigurasi platform agentic untuk agen data yang didukung Looker, terapkan praktik terbaik berikut:

  • Jangan meminta secret kepada pengguna: Konfigurasikan agen root agar tidak pernah meminta pengguna akhir menempelkan atau memberikan kredensial Looker API dalam chat.
  • Gunakan akun pengguna Looker API khusus: Buat pengguna Looker API khusus dengan izin hak istimewa terendah yang dicakupkan hanya ke model dan Jelajah yang diperlukan agen data.
  • Memasukkan kredensial di luar konteks model: Konfigurasikan platform, middleware klien MCP, atau lapisan proxy Anda untuk memasukkan kredensial Looker API ke dalam payload permintaan chat di lapisan transport atau eksekusi alat. Jangan tempatkan rahasia klien dalam petunjuk perintah atau histori percakapan agen root.

Pola injeksi kredensial untuk platform agentic

Untuk menjaga kerahasiaan di luar jendela konteks model, platform biasanya memasukkan kredensial Looker menggunakan salah satu pendekatan berikut:

  • Intersepsi proxy atau middleware klien MCP: Di platform yang mendukung middleware permintaan, gateway API, atau hook intersepsi alat, agen root menghasilkan panggilan alat chat yang hanya berisi parameter semantik (parent, dataAgentContext, dan messages). Lapisan middleware mengintersepsi permintaan JSON-RPC keluar sebelum mencapai https://geminidataanalytics.googleapis.com/mcp, membaca kredensial dari penyimpanan secret yang aman atau variabel lingkungan, dan mengisi objek credentials.
  • Definisi alat yang digabungkan: Dalam framework agen kustom (seperti Agent Development Kit (ADK) atau orchestrator Python kustom), ekspos versi gabungan alat chat ke agen root yang menghilangkan parameter credentials dari skema alat. Pengendali eksekusi wrapper melampirkan blok credentials secara terprogram dari konfigurasi yang aman sebelum meneruskan panggilan ke server MCP Analisis Percakapan API.

Contoh berikut menunjukkan payload permintaan JSON-RPC lengkap yang dikirim klien MCP ke server MCP jarak jauh untuk alat chat. Meskipun model menghasilkan parameter parent, dataAgentContext, dan messages, platform host atau middleware klien MCP mengisi objek credentials sebelum mengirimkan permintaan:

{
  "parent": "projects/PROJECT_ID/locations/LOCATION",
  "dataAgentContext": {
    "dataAgent": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
  },
  "credentials": {
    "oauth": {
      "secret": {
        "clientId": "LOOKER_CLIENT_ID",
        "clientSecret": "LOOKER_CLIENT_SECRET"
      }
    }
  },
  "messages": [
    {
      "userMessage": {
        "text": "USER_QUESTION"
      }
    }
  ]
}

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud Anda
  • LOCATION: lokasi resource API Analisis Percakapan Anda (misalnya, global)
  • AGENT_ID: ID agen data yang didukung Looker
  • LOOKER_CLIENT_ID: client ID untuk pengguna Looker API Anda
  • LOOKER_CLIENT_SECRET: rahasia klien untuk pengguna Looker API Anda
  • USER_QUESTION: perintah atau pertanyaan yang akan dikirim ke agen data

Memverifikasi koneksi dengan perintah pengujian

Setelah menautkan koneksi MCP kustom ke aplikasi agen, buka antarmuka chat platform, beri otorisasi sesi pengguna saat diminta, dan kirim perintah pengujian untuk mengonfirmasi bahwa agen root dapat memanggil alat MCP Analisis Percakapan API dan mengkueri BigQuery menggunakan kredensial yang didelegasikan.

Jika Anda mengonfigurasi petunjuk sistem di bagian sebelumnya, Anda dapat mengajukan pertanyaan langsung ke agen data, atau menjalankan kueri pengujian terhadap set data publik BigQuery dengan menentukan project, lokasi, dan set data dalam prompt Anda:

What are the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales?

Anda juga dapat secara eksplisit menginstruksikan agen root untuk memanggil alat chat dari konektor MCP Anda (CONNECTOR_NAME):

Use the chat tool from CONNECTOR_NAME to find the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales.

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: IDGoogle Cloud project tempat Anda mengaktifkan Analisis Percakapan API
  • LOCATION: lokasi resource Analisis Percakapan API Anda (misalnya, global)
  • CONNECTOR_NAME: nama yang Anda tetapkan ke koneksi MCP kustom di platform agentic Anda (misalnya, ca-mcp-prod)

Langkah berikutnya