Menggunakan server MCP jarak jauh Agent Retrieval untuk terhubung ke aplikasi AI dan kustom

Dokumen ini menunjukkan cara menggunakan server Model Context Protocol (MCP) jarak jauh Gemini Enterprise Agent Platform untuk terhubung dengan aplikasi AI, termasuk Gemini CLI, ChatGPT, Claude, dan aplikasi kustom yang Anda kembangkan. Server MCP jarak jauh Agent Retrieval memungkinkan Anda mengakses dan menjalankan alat Agent Retrieval untuk memeriksa koleksi dan indeks, serta melakukan penelusuran vektor, semantik, hybrid, dan teks atas data Anda dari lingkungan pengembangan yang mendukung AI dan platform agen AI. Server MCP jarak jauh Gemini Enterprise Agent Platform diaktifkan saat Anda mengaktifkan Gemini Enterprise Agent Platform API.

Model Context Protocol (MCP) menstandarkan 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 dijalankan di komputer lokal Anda dan menggunakan aliran input dan output 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.

Core stateless

Dengan MCP versi 28-07-2026, MCP berubah dari protokol stateful dua arah menjadi protokol stateless. Setiap permintaan MCP bersifat deskriptif dan dapat dirutekan menggunakan header. Tidak perlu handshake initialize/initialized atau Mcp-Session-Id karena setiap permintaan menyertakan semua informasi yang diperlukan dalam header HTTP atau parameter _meta. Server MCP dapat meminta informasi tambahan yang diperlukan oleh alat melalui permintaan multi-round-trip (MRTR).

Untuk membantu merutekan dan memproses permintaan tanpa mengurai isi permintaan, beberapa header MCP diperlukan, termasuk:

  • Header yang diperlukan oleh spesifikasi MCP seperti header versi protokol dan header permintaan standar.
  • Header kustom yang ditentukan oleh server MCP. Header ini dicerminkan ke dalam header HTTP dari skema input alat menggunakan properti x-mcp-header. Misalnya, server MCP dapat menentukan header kustom untuk menentukan region atau project ID Cloud de Confiance by S3NS .

Untuk mengetahui informasi selengkapnya tentang arsitektur MCP, lihat spesifikasi dan perubahan utama MCP versi 28-07-2026.

Server MCP jarak jauh Cloud de Confiance by S3NS dan Google

Server MCP jarak jauh Google dan Cloud de Confiance by S3NS memiliki fitur dan manfaat berikut:

  • Penemuan yang disederhanakan dan terpusat
  • Endpoint HTTP global atau regional terkelola
  • 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. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

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

  3. Aktifkan Agent Retrieval API, jika belum diaktifkan.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Mengaktifkan API

Peran yang diperlukan

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

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 Agent Retrieval. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan server MCP Agent Retrieval:

  • Melakukan panggilan alat MCP: mcp.tools.call
  • Membuat daftar dan memeriksa koleksi dan indeks: vectorsearch.collections.list, vectorsearch.collections.get, vectorsearch.indexes.list, vectorsearch.indexes.get
  • Membaca dan menelusuri objek data: vectorsearch.dataObjects.get, vectorsearch.dataObjects.query, vectorsearch.dataObjects.search

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

Server MCP Agent Retrieval hanya mengekspos alat hanya baca; tidak diperlukan izin tulis.

Autentikasi dan otorisasi

Server MCP Agent Retrieval menggunakan protokol OAuth 2.0 dengan IAM untuk autentikasi dan otorisasi. Semua identitasCloud de Confiance by S3NS didukung untuk autentikasi ke server MCP.

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

Cakupan OAuth MCP Agent Retrieval

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

Server MCP Agent Retrieval menerima cakupan OAuth berikut:

URI Cakupan Deskripsi
https://www.googleapis.com/auth/cloud-platform Memberikan akses luas ke semua layanan Cloud de Confiance by S3NS , termasuk semua fitur Agent Retrieval.

Mengonfigurasi klien MCP untuk menggunakan server MCP Agent Retrieval

Aplikasi dan agen AI, seperti Claude atau Antigravity, dapat membuat instance klien MCP yang terhubung ke satu server MCP. Aplikasi AI dapat memiliki beberapa klien yang terhubung ke server MCP yang berbeda. Jika aplikasi Anda tidak tercantum dalam panduan khusus klien, Anda dapat menggunakan informasi berikut untuk terhubung dari sebagian besar aplikasi.

Di aplikasi AI Anda, cari cara untuk menambahkan atau terhubung ke server MCP jarak jauh. Untuk server MCP Agent Retrieval, masukkan informasi berikut sesuai kebutuhan:

  • Server name: Agent Retrieval MCP server

  • URL Server atau Endpoint: https://vectorsearch.googleapis.com/mcp

    Endpoint tunggal ini mengekspos kesembilan alat MCP Agent Retrieval. Panggilan alat dikirim ke backend yang benar melalui pemilihan rute berbasis header.

  • Transport: HTTP yang dapat di-streaming

  • Detail autentikasi: kredensial Cloud de Confiance by S3NS Anda, Client ID dan rahasia OAuth, atau identitas dan kredensial agen. Untuk mengetahui informasi selengkapnya tentang autentikasi, lihat Melakukan autentikasi ke server MCP.

Pemilihan rute berbasis header dan persyaratan protokol klien

Server MCP Agent Retrieval mengirimkan setiap tools/call di edge jaringan berdasarkan dua header HTTP:

  • Mcp-Name — harus sama dengan nama alat dalam isi permintaan (params.name).
  • Mcp-Param-Region — harus sama dengan komponen location dari jalur resource dalam isi permintaan (misalnya, us-central1 untuk Koleksi di projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

Jika salah satu header tidak ada atau tidak cocok dengan isi, permintaan akan ditolak dengan HTTP 400 Bad Request.

Klien MCP Anda harus memunculkan header ini secara dinamis per tools/call. Perilaku ini distandardisasi dalam protokol MCP versi 2026-07-28 dan yang lebih baru; pastikan library klien MCP Anda mengiklankan setidaknya versi protokol ini selama handshake initialize. Klien yang disematkan ke versi protokol sebelumnya, atau versi SDK yang tidak mendukung emisi header dinamis, tidak dapat menggunakan server MCP Agent Retrieval melalui endpoint /mcp terpadu.

URI Pengalihan

Untuk aplikasi berbasis web, dan beberapa aplikasi desktop, Anda harus mengizinkan URI pengalihan saat membuat client ID dan rahasia untuk autentikasi. URI pengalihan digunakan oleh server otorisasi untuk mengirim token ke aplikasi Anda. Dokumentasi aplikasi Anda harus menentukan URI pengalihan yang harus Anda gunakan. URI pengalihan kustom tidak didukung.

Untuk panduan khusus aplikasi tentang cara menyiapkan dan menghubungkan ke server MCP, lihat Panduan khusus klien.

Untuk panduan yang lebih umum, lihat referensi berikut:

Alat yang tersedia

Server MCP Agent Retrieval mengekspos sembilan alat hanya baca:

Alat Deskripsi
list_collections Mencantumkan koleksi Agent Retrieval dalam project dan lokasi.
get_collection Mengambil skema dan metadata koleksi tertentu.
list_indexes Mencantumkan indeks yang ditentukan pada koleksi.
get_index Mengambil konfigurasi indeks tertentu.
get_data_object Mengambil objek data berdasarkan ID dari koleksi.
search_data_objects Menjalankan penelusuran vektor, semantik, atau teks terhadap koleksi.
query_data_objects Membuat daftar objek data yang cocok dengan ekspresi filter.
batch_search_data_objects Menjalankan beberapa penelusuran secara paralel dan menggabungkan hasilnya dengan Reciprocal Rank Fusion (RRF) atau Vertex Ranking API.
aggregate_data_objects Menggabungkan objek data yang cocok dengan ekspresi filter (misalnya, jumlah).

Semua alat bersifat hanya baca; server MCP tidak mengekspos operasi tulis, update, atau hapus pada resource Agent Retrieval.

Alat daftar

Gunakan MCP inspector untuk mencantumkan alat, atau kirim permintaan HTTP tools/list langsung ke server MCP Agent Retrieval. Metode tools/list tidak memerlukan autentikasi.

Server MCP Agent Retrieval mendukung protokol stateless MCP 2026-07-28, sehingga setiap permintaan stateless bersifat deskriptif dan harus mendeklarasikan versi protokol di header HTTP MCP-Protocol-Version dan kolom isi _meta.io.modelcontextprotocol/protocolVersion, beserta objek _meta.io.modelcontextprotocol/clientCapabilities (objek kosong diterima). Header HTTP Mcp-Method juga harus cocok dengan method dalam isi.

curl -X POST 'https://vectorsearch.googleapis.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Kasus penggunaan sampel

Berikut adalah contoh kasus penggunaan untuk server MCP Agent Retrieval:

  • Pemeriksaan resource: mencantumkan koleksi dan indeks dalam project, serta memeriksa skema dan metadatanya.
  • Penelusuran vektor dan semantik: menjalankan penelusuran vektor atau penelusuran semantik terhadap koleksi untuk menemukan Objek Data yang paling relevan untuk kueri.
  • Pengambilan campuran: gabungkan penelusuran semantik, teks, dan Penelusuran Vektor dalam satu panggilan batch dan gabungkan hasilnya dengan Reciprocal Rank Fusion (RRF) atau Vertex Ranking API.
  • Pengambilan objek data: mengambil objek data individual berdasarkan ID, atau mengkueri koleksi berdasarkan filter untuk memeriksa data yang diserap.

Contoh perintah

  • "Cantumkan koleksi Agent Retrieval di project PROJECT_ID di REGION."
  • "Tampilkan skema koleksi COLLECTION_ID di region REGION."
  • "Jalankan penelusuran semantik pada koleksi COLLECTION_ID untuk QUERY_TEXT dan tampilkan 5 tetangga terdekat."
  • "Lakukan penelusuran hybrid pada koleksi COLLECTION_ID untuk QUERY_TEXT yang menggabungkan penelusuran semantik dan teks, lalu beri peringkat ulang 50 hasil teratas dengan semantic-ranker-fast@latest."
  • "Dapatkan objek data dengan ID DATA_OBJECT_ID dari koleksi COLLECTION_ID."

Dalam perintah, ganti kode berikut:

  • PROJECT_ID: project ID Cloud de Confiance
  • REGION: region koleksi Anda (misalnya, us-central1)
  • COLLECTION_ID: ID koleksi Agent Retrieval
  • DATA_OBJECT_ID: ID objek data dalam koleksi
  • QUERY_TEXT: teks bahasa alami kueri

Kuota dan batas

Server MCP Agent Retrieval tidak memiliki kuotanya sendiri. Tidak ada batasan jumlah panggilan yang dapat dilakukan ke server MCP. Anda tetap tunduk pada kuota yang diberlakukan oleh Agent Retrieval API, yang dipanggil oleh alat server MCP atas nama Anda. Untuk mengetahui informasi selengkapnya, lihat Kuota Agent Retrieval.

Langkah berikutnya