Standar integrasi aplikasi terhubung MCP

Server MCP membuat framework untuk menghubungkan fungsi aplikasi Anda (alat MCP) ke Platform Aplikasi Terhubung. Agar dapat memilih, memanggil, dan memproses hasil layanan Anda dengan lebih andal, konfigurasi MCP Anda harus mematuhi standar berikut dengan ketat.

Prinsip-prinsip Pemandu

Untuk setiap fungsi, fokuslah pada niat pengguna dan kasus penggunaan, bukan kemampuan fungsi. Deskripsi adalah cara utama Anda untuk memberi tahu model tentang fungsi alat Anda dan kasus penggunaan yang dapat diresponsnya.

Pembuatan versi

Untuk mendukung deployment MCP yang skalabel dan andal, gunakan arsitektur URI terstruktur yang memanfaatkan pembuatan versi berbasis jalur—misalnya, /v1, /v2. Tindakan ini akan membantu Anda mempertahankan kompatibilitas mundur, dan membatasi fitur baru. Melengkapi hal ini dengan subdomain khusus penyedia, seperti https://gemini.mcp.company.com/mcp/v1, memungkinkan pengelolaan traffic yang terperinci dan pengoptimalan definisi alat yang disesuaikan dengan konteks unik dan perilaku pemrosesan berbagai model AI.

Penting: Jika Anda menggunakan subdomain khusus Gemini, pastikan metadata /.well-known/oauth-protected-resource dan audiens token/validasi resource RFC 8707-nya cocok dengan subdomain tersebut.

Kompatibilitas versi protokol MCP

Platform Aplikasi Terhubung mendukung spesifikasi Model Context Protocol (MCP) hingga versi 2025-11-25. Rilis spesifikasi yang lebih baru belum didukung.

• Tanggung jawab developer: Anda bertanggung jawab untuk memastikan server MCP Anda benar-benar mematuhi versi protokol yang didukung oleh Connected Apps Platform (2025-11-25) selama handshake initialize dan di semua definisi alat dan skema.
• Kompatibilitas mundur platform: Seiring Platform Aplikasi Terhubung mengadopsi versi spesifikasi MCP yang lebih baru pada masa mendatang, klien kami akan mempertahankan kompatibilitas mundur dengan versi protokol yang didukung sebelumnya sehingga integrasi produksi yang ada terus berfungsi tanpa gangguan.
• Mengelola upgrade: Jika Anda siap mengadopsi spesifikasi MCP yang baru didukung atau memperkenalkan perubahan skema, ekspos update tersebut di jalur URI berversi baru (misalnya, /mcp/v2) sambil mempertahankan endpoint yang ada (/mcp/v1) untuk traffic aktif.

Peringatan: Produk Google yang berlaku tidak mengizinkan perubahan dinamis pada skema MCP. Selama pendaftaran untuk keamanan dan uji mutu, snapshot diambil dari skema MCP—termasuk daftar alat, argumennya, dan petunjuk server. Mengubah skema server MCP dapat merusak integrasi dan dapat menyebabkan aplikasi dinonaktifkan.

Perubahan pada skema MCP diizinkan di antara versi aplikasi. Sebaiknya Anda memanfaatkan fitur ini dan membuat versi endpoint MCP untuk mendukung peluncuran fitur baru secara bertahap, atau hanya mengandalkan perubahan yang kompatibel dengan versi lama.

Spesifikasi protokol transport

Platform Aplikasi Terhubung hanya mendukung spesifikasi Model Context Protocol transportasi HTTP yang Dapat Di-streaming versi 26-03-2025 dan yang lebih baru. API ini tidak mendukung HTTP lama dengan transport SSE yang dijelaskan oleh spesifikasi 2024-11-05.

• Endpoint HTTP tunggal. Endpoint MCP yang disediakan di Konsol Terhubung (misalnya, https://api.example.com/mcp) adalah URL tunggal tempat produk Google yang berlaku mengirim semua permintaan JSON-RPC (initialize, tools/list, tools/call) melalui HTTP POST standar.
• Streaming SSE dalam HTTP yang dapat di-streaming. Transpor SSE multi-endpoint lama tidak didukung, tetapi Peristiwa yang Dikirim Server seperti text/event-stream didukung dalam Streamable HTTP. Permintaan keluar dari produk Google yang berlaku menyertakan Accept: application/json, text/event-stream, yang berarti server Anda dapat menampilkan payload application/json standar atau menstreaming respons inkremental menggunakan Content-Type: text/event-stream langsung di isi respons HTTP POST.
• Streaming GET & 405 Method Not Allowed. Klien dapat mencoba streaming GET opsional di endpoint untuk notifikasi server ke klien. Jika server Anda bersifat stateless atau hanya request-response, menampilkan HTTP 405 Method Not Allowed didukung secara eksplisit dan ditangani dengan baik oleh proxy klien produk Google yang berlaku.

Petunjuk server

Platform Aplikasi Terhubung dioptimalkan untuk menyerap petunjuk server, sehingga memungkinkan tingkat kontrol atas perilaku model yang tidak tersedia melalui cara lain.

Ikuti petunjuk server.

Perlakukan sebagai "petunjuk model" dengan konteks penggunaan

Ikuti panduan berikut terkait pemberian petunjuk kepada model.

• Tulis petunjuk sebagai "petunjuk" atau panduan tingkat tinggi untuk membantu LLM memahami tujuan dan kemampuan server secara keseluruhan.
• Jelaskan apa yang dapat dilakukannya, alih-alih mencantumkan fitur atau menjelaskan cara model harus menggunakan alat dan resource server. Jika model memahami "apa" dengan benar, model dapat menentukan cara yang cukup baik berdasarkan perjalanan pengguna.
• Asumsikan teks ini akan ditambahkan langsung ke perintah sistem model. Buat perintah yang jelas, direktif, dan efisien token.

Lengkapi, dan jangan duplikasi

Gunakan ruang ini untuk konteks global yang berlaku di semua alat, sehingga menghindari redundansi dengan deskripsi alat individual.

Contoh petunjuk server

Contoh berikut menunjukkan hal yang boleh dan tidak boleh dilakukan terkait penulisan petunjuk server yang benar.

Direkomendasikan

Tidak direkomendasikan

Berperanlah sebagai pengelola repositori GitHub khusus. Server ini memberikan akses mendalam ke metadata repositori, pelacakan masalah, dan alur kerja PR. Gunakan untuk menjaga kondisi project, mengotomatiskan triase, dan memastikan standar kode. Asumsikan semua tindakan dilakukan dalam konteks organisasi yang diautentikasi, kecuali jika ditentukan lain. Prioritaskan identifikasi rangkaian pesan yang tidak aktif atau PR yang tidak ditautkan agar repositori tetap teratur. Ringkas, direktif, dan melengkapi model Menentukan "apa" (kesehatan project, triase), bukan "bagaimana" Menyebutkan cakupan autentikasi yang berlaku untuk semua alat

Server ini memiliki alat untuk GitHub. Anda harus menggunakan alat list_issues saat pengguna menanyakan masalah. Anda dapat menggunakan create_pull_request untuk membuat PR. Gunakan alat ini dengan hati-hati untuk membantu pengguna mengelola kodenya. Selalu periksa nama repositori sebelum memanggil alat. Jika pengguna meminta ringkasan, panggil alat terlebih dahulu, lalu ringkas outputnya jangan mencantumkan ulang nama alat, jangan memberi tahu model "cara" berpikir yang dapat bertentangan dengan penalaran bawaan model yang akan menggunakan konteks pengguna untuk membuat pilihan yang tepat. tidak menjelaskan sifat akses server atau batasan spesifiknya)

Panduan alat

Panduan berikut menjelaskan praktik terbaik untuk membuat konfigurasi server MCP untuk berbagai fungsi, atau alat, dalam aplikasi Anda.

Konvensi penamaan alat

Perhatikan panduan berikut untuk memberi nama alat Anda:

Menggunakan nama yang intuitif dan dapat dibaca manusia

Gunakan nama yang dapat dibaca manusia dengan makna yang jelas dan intuitif, bukan yang ambigu. Misalnya, get_user_information lebih mudah dipahami daripada userInfo.

Perhatikan gaya penulisan huruf yang tepat

Patuhi aturan penggunaan huruf besar/kecil berikut untuk nama fungsi alat dan pemicu aplikasi:

• Casing fungsi alat. Gunakan snake_case atau camelCase untuk nama fungsi alat yang ditentukan dalam skema MCP Anda (misalnya, get_user_information atau publishDraft).
• Casing pemicu aplikasi. Pemicu dan sebutan aplikasi (misalnya, @MyTwoWordApp) tidak peka huruf besar/kecil. Platform menormalisasi input pengguna di seluruh huruf kecil (@mytwowordapp), PascalCase (@MyTwoWordApp), dan camelCase (@myTwoWordApp).
• Pemformatan nama tampilan. Daftarkan judul aplikasi resmi Anda menggunakan PascalCase atau spasi standar untuk tampilan visual yang jelas di elemen UI.
• Penanganan kesalahan ketik. Meskipun variasi huruf besar/kecil ditangani secara otomatis, kesalahan ketik karakter (misalnya, @mytwowrodapp) mengandalkan pengenalan intent penggantian, bukan pencocokan string langsung. Developer harus mendorong ejaan nama sebutan channel yang akurat dalam dokumentasi.

Menggunakan penamaan kata kerja-kata benda yang eksplisit

Gunakan penamaan verb_noun yang spesifik, dan hindari ambiguitas—misalnya, publish_draft lebih baik daripada handle_content.

Perincian alat

Perhatikan panduan berikut terkait perincian alat.

Memperlakukan alat sebagai endpoint atomik

Perlakukan alat sebagai endpoint atomik tanpa kondisi alat di dalamnya atau beberapa fungsi dengan parameter yang diperlukan masing-masing. Alat yang terperinci memungkinkan model merangkai langkah-langkah secara logis, sehingga mengurangi halusinasi.

Menggunakan skema yang lebih sederhana

Jika Anda memerlukan objek bertingkat yang dalam atau logika skema oneOf / anyOf yang kompleks untuk memvalidasi input, alat Anda mungkin terlalu luas.

Mematuhi aturan pra-agregasi dan payload

Meskipun pra-penggabungan data tidak diterapkan secara ketat oleh protokol untuk payload kecil yang tercakup, pra-penggabungan backend sangat diperlukan dalam praktiknya saat bekerja dengan set data besar, histori longitudinal, dan set data multi-sumber. Platform Aplikasi Terhubung menerapkan batasan seputar batas jendela konteks, latensi eksekusi, dan langkah-langkah penalaran model. Untuk mematuhi batasan ini, ikuti panduan berikut:

• Filter dan ringkas di backend. Selalu filter, lakukan pra-agregasi, atau ringkas aliran data besar di server MCP Anda sebelum menampilkan respons ke produk Google yang berlaku.
• Hindari dump mentah. Jangan pernah membuang baris database mentah atau log lengkap yang tidak diindeks ke dalam payload yang ditampilkan alat.

Menghilangkan alat internal dan meta

Hanya ekspos kemampuan yang ditampilkan model dalam respons tools/list server Anda:

• Filter alat bantuan: Hilangkan alat internal, administratif, atau meta yang tidak dimaksudkan untuk dipanggil oleh model (misalnya, health check server, rutinitas penyiapan internal, atau helper utilitas developer).
• Efisiensi jendela konteks: Dengan mengecualikan alat yang tidak diperlukan, skema MCP Anda akan tetap ringkas, konsumsi token jendela konteks akan berkurang, dan kebingungan pemilihan rute alat model akan dicegah. Server MCP yang mengekspos puluhan alat atau skema 'mega-alat' yang sangat bertingkat akan ditandai selama peninjauan untuk diperbaiki.

Anjuran dan larangan terkait perincian alat

Contoh berikut menunjukkan hal yang boleh dan tidak boleh dilakukan terkait penamaan alat dan penggunaan perincian.

Direkomendasikan

Tidak direkomendasikan

Alat terperinci dengan nama dan parameter yang jelas Skema input untuk setiap alat bersifat ketat. Jika LLM ingin membuat pengguna, LLM harus memberikan email. Jika ingin menghapus, ID harus diberikan. Tidak ada tebakan. ... @mcp.tool() def create_user(email: str, role: str = "viewer") -> str: """Register a new user. Returns the new User ID.""" # Logic is purely creation return "user_123" @mcp.tool() def delete_user(user_id: str) -> str: """Permanently remove a user by their ID.""" # Logic is purely deletion return f"User {user_id} deleted" @mcp.tool() def update_user_role(user_id: str, new_role: str) -> str: """Change an existing user's permission level.""" return f"User {user_id} is now {new_role}" ...

Nama Alat: manage_user Deskripsi: "Gunakan alat ini untuk membuat, memperbarui, menghapus, atau mengambil pengguna." ... @mcp.tool() def manage_user( action: Literal["create", "update", "delete", "get"], user_id: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = "viewer" ) -> str: """ Use this to manage users. WARNING: logic is hidden inside Python, not visible in the schema. """ if action == "create": if not email: return "Error: Email required for creation" # Runtime error, not schema error return f"Created user {email}" elif action == "delete": if not user_id: return "Error: User ID required" return f"Deleted {user_id}" return "Action completed" """ ...

Mendeklarasikan anotasi alat untuk keamanan

Konfigurasikan anotasi protokol di dalam definisi alat Anda untuk menyampaikan perilaku eksekusi dan memicu gerbang keamanan bawaan di seluruh produk Google yang berlaku:

• Gerbang konfirmasi runtime: produk Google yang berlaku menggunakan annotations.destructiveHint: true dan annotations.openWorldHint: true sebagai flag utama untuk memicu dialog konfirmasi pengguna runtime. Deklarasikan destructiveHint: true pada tindakan yang mengubah status, menulis, atau merusak, dan tetapkan openWorldHint: true untuk alat yang berinteraksi dengan lingkungan open-world atau eksternal sehingga platform secara native meminta konfirmasi pengguna sebelum eksekusi.
• Petunjuk kueri hanya baca: tetapkan readOnlyHint: true pada alat kueri yang hanya mengambil data tanpa mengubah status backend.
• Default anotasi eksplisit: sesuai dengan spesifikasi Model Context Protocol, menghilangkan readOnlyHint akan menyebabkan klien mengasumsikan readOnlyHint: false dan destructiveHint: true secara default demi keamanan. Mendeklarasikan anotasi secara eksplisit pada semua alat akan memastikan perutean model yang dapat diprediksi dan keamanan eksekusi yang tepat.

Deskripsi alat

Deskripsi adalah satu-satunya konteks yang dimiliki model untuk memutuskan apakah alat Anda dapat menyelesaikan masalah saat ini. Perhatikan panduan berikut untuk menulis deskripsi:

Tulis petunjuk, bukan komentar

Tulis deskripsi alat sebagai petunjuk, bukan sebagai komentar kode, yang sering kali bersifat pasif. LLM merespons perintah dengan baik.

Jelaskan "caranya"

Deskripsi yang baik menjembatani kesenjangan antara "Saya memiliki alat" dan "Saya tahu cara menghubungkan alat ini ke dalam percakapan".

Jelaskan "alasannya"

Bedakan alat ini dari alat serupa—misalnya, "Gunakan alat ini untuk pengguna internal, gunakan customer_update untuk pengguna eksternal".

Berikan link

Beri tahu model tempat menemukan argumen—misalnya, "dari alat order_search".

Menentukan format

Tentukan satuan (meter versus kaki) dan format (tanggal ISO, versi semantik).

Menghindari diskresi model

Jangan menginstruksikan model untuk menggunakan "penilaian terbaiknya" atau menyarankan tindakan opsional yang tidak dipandu.

Contoh deskripsi alat

Contoh berikut menunjukkan hal yang boleh dan tidak boleh dilakukan terkait penulisan deskripsi alat.

Direkomendasikan	Tidak direkomendasikan
Sumber tepercaya "Memperbarui email pengguna. Harus benar-benar menggunakan 'id' UUID yang ditampilkan dari alat search_users. Jangan menyimpulkan atau menebak ID pengguna." (Alat ini secara eksplisit menautkan output dari satu alat ke input alat ini.)	"Memperbarui alamat email pengguna." (Model mungkin menebak ID seperti 12345.)
Format dan batasan "Jadwalkan rapat. 'date' harus dalam format ISO 8601 (YYYY-MM-DD). Jika pengguna mengatakan 'besok' atau referensi relatif lainnya, hitung tanggal berdasarkan konteks saat ini."	"Jadwalkan rapat untuk tanggal yang ditentukan." (terlihat benar bagi manusia (misalnya, "besok"), tetapi gagal dalam validasi skema (memerlukan "2025-10-12"))
Ekspektasi output "Mengambil log server. Menampilkan 50 baris terakhir teks mentah. Untuk analisis, minta rentang waktu yang lebih kecil untuk menghindari batas token."	"Dapatkan log server". (Model mungkin memanggil alat yang mengharapkan ringkasan, mendapatkan dump JSON mentah berukuran 5 MB, dan dapat mengakibatkan pengalaman pengguna yang buruk.)
@mcp.tool() def update_campaign_status(campaign_id: str, status: str) -> str: """ Promotes or pauses an advertising campaign. CRITICAL USAGE RULES: 1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'. 2. 'status': Must be exactly one of: ['active', 'paused', 'archived']. Returns: A confirmation string with the new status and timestamp. """ # Logic... ... Deskripsi ini berfungsi sebagai panduan singkat. Class ini menangani Sumber (tempat mendapatkan ID), Batasan (enum yang valid), dan Tindakan.	@mcp.tool() def update_campaign_status(id: str, status: str) -> str: """ Updates the campaign status in the database. """ # Logic... Hal ini mengandalkan nama variabel untuk melakukan semua pekerjaan. Model akan menebak nilai yang valid untuk "status"

Parameter alat

Selain alat itu sendiri, jelaskan parameter untuk membuatnya tidak ambigu.

Jenis eksplisit

Gunakan jenis yang kuat dan spesifik (string, integer, boolean, array).

Menggunakan enum untuk kumpulan nilai tetap

Jika parameter hanya menerima kumpulan nilai tetap (misalnya, daylight, cool, warm), cantumkan dalam array enum. Hal ini meningkatkan akurasi secara signifikan.

Menyatakan parameter yang diperlukan dengan jelas

Tentukan dengan jelas parameter yang wajib ada agar fungsi dapat beroperasi.

Menerapkan pencocokan skema semantik

Saat mengintegrasikan aplikasi, pencocokan skema semantik dari parameter alat dengan vertical yang Anda kembangkan mungkin diperlukan. Anda akan menerima skema vertikal yang diharapkan (skema JSON) selama proses aktivasi.

Contoh parameter alat

Contoh berikut menunjukkan hal yang boleh dan tidak boleh dilakukan terkait penanganan parameter alat.

Direkomendasikan	Tidak direkomendasikan
Format dan unit argumen radius: "Radius dalam meter. Harus berupa float > 0." (mencegah halusinasi unit)	radius: "Radius lingkaran."
Format dan konteks ID user_id: "UUID database (misalnya, 550e8400-e29b...). Jangan gunakan alamat email di sini." Catatan: Sebagai praktik terbaik, semua kolom ID numerik harus diperlakukan sebagai nilai String. Khususnya, jika ID Anda dapat berisi 10+ digit, Anda berisiko ID tersebut dipotong oleh sistem internal (dipaksa masuk ke container 32 bit) dan versi ini digunakan oleh model dalam panggilan alat di masa mendatang. (mencegah error jenis)	user_id: "ID pengguna."
Ekspektasi nilai hasil "Memperbarui data dan menampilkan objek JSON yang diperbarui, termasuk stempel waktu baru." (Memberi tahu model bahwa model tidak perlu memanggil alat "get" segera setelah "update" untuk memverifikasi perubahan.)	"Memperbarui data."
@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """ Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth'). Args: query: A Lucene-formatted search string. limit: Max results to return. capped at 50. Returns: A formatted string of log entries with timestamps. """ ...	@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """Searches the logs.""" ... LLM tidak mengetahui sintaksis yang didukung "query" (SQL? Regex? Teks biasa?) Model tidak mengetahui "batas" maksimumnya.

Respons dan penanganan error

Sesuai dengan prinsip inti Respons adalah perintah berikutnya, alat ini melaporkan hasil eksekusi yang mendasarinya dengan menampilkan payload data, yang kemudian ditempelkan langsung ke dalam jendela konteks LLM. Keberhasilan atau kegagalan hasil akan menentukan apa yang terjadi selanjutnya:

• Jika berhasil: model memerlukan nilai yang ditampilkan untuk mengetahui apa yang terjadi guna memutuskan langkah berikutnya.
• Jika gagal: model perlu mengetahui alasan kegagalan dan cara memperbaikinya. Error (error 500) menghentikan percakapan; pesan error deskriptif memungkinkan model melakukan koreksi mandiri.

Terlepas dari apakah logika dasar alat Anda berhasil atau gagal, Anda harus memformat payload nilai yang ditampilkan agar model dapat mengurainya dengan mudah. Ikuti praktik terbaik berikut saat mengemas payload respons Anda.

Menggunakan JSON

Memformat data terstruktur di TextContent (Batasan sementara). Karena structuredContent belum didukung di Platform Aplikasi Terhubung, serialisasikan data Anda secara manual. Meskipun menampilkan daftar yang sederhana, json.dumps().

Menyertakan URL dalam respons

URL yang ditampilkan harus relatif singkat dan tanpa banyak parameter. Sebaiknya gunakan layanan penyingkatan URL untuk menghemat jumlah token dan mengurangi risiko halusinasi.

Payload anti-halusinasi yang deskriptif

Selalu pasangkan kode mentah atau ID internal dengan nama tampilan yang dapat dibaca manusia, unit pengukuran eksplisit, dan rentang referensi. Jangan pernah menampilkan kunci kamus yang dikompresi atau kode numerik yang tidak dipetakan yang memaksa model untuk menyimpulkan konteks.

Terapkan penanganan error yang andal

Tampilkan pesan error yang jelas dan bermakna agar model dapat memahami masalah yang terjadi dan memberi tahu pengguna. Lihat Penanganan error MCP.

Menggunakan try/except

Gabungkan logika alat dalam blok try/except dan tampilkan error yang diubah menjadi string.

Memberikan error yang dapat ditindaklanjuti

Sarankan langkah berikutnya dalam pesan error (misalnya, "Coba gunakan alat X terlebih dahulu").

Konfirmasi tindakan

Jangan tampilkan string kosong untuk alat efek samping (buat/perbarui/hapus).

Contoh respons dan penanganan error

Contoh berikut menunjukkan hal yang boleh dan tidak boleh dilakukan terkait respons dan penanganan error.

Direkomendasikan	Tidak direkomendasikan
Serialisasi eksplisit ... import json @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON return json.dumps(result, indent=2)	... @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON return str(result)
Mendeteksi dan menginformasikan ... @mcp.tool() def get_user_details(user_id: str) -> str: try: user = db.get_user(user_id) if not user: # GOOD: Informative error returned as content return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'." return json.dumps(user) except Exception as e: return f"Error: Database connection failed ({str(e)}). Please try again later." (Alat ini secara teknis "berhasil" (menampilkan string), tetapi string tersebut berisi detail error. Model akan membaca ini, menyadari "Oh, ID itu tidak ada", dan dapat meminta ID yang benar kepada pengguna.)	... @mcp.tool() def get_user_details(user_id: str) -> str: # BAD: Unhandled exception if ID not found user = db.get_user(user_id) return json.dumps(user) (Jika get_user gagal, server akan menampilkan 500. LLM menerima error eksekusi umum dan tidak tahu penyebabnya (Apakah ID-nya salah? Database tidak aktif? Izin ditolak?). Kemungkinan, model akan mencoba lagi input buruk yang sama persis.)
Respons Kosong ... @mcp.tool() def post_story(story_content: str) -> str: service_name = "story_service" api_client.post("/stories", json={"content": story_content}) # GOOD: Explicit confirmation of state change. return f"Service '{service_name}' successfully posted content. Status is now 'posted'."	... @mcp.tool() def post_story(storyContent: str): subprocess.post(["postsrv", "story", storyContent]) # BAD: Returns null/empty string. Model is confused. LLM sering kali bingung dengan respons kosong. Model mungkin berhalusinasi "Alat gagal" atau hanya mengulangi panggilan.
Payload anti-halusinasi yang deskriptif mandiri Selalu pasangkan kode mentah atau ID internal dengan nama tampilan yang dapat dibaca manusia, unit pengukuran eksplisit, dan rentang referensi normal. {"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"} (Hal ini memberi tahu model arti nilai tersebut secara tepat tanpa memaksanya menyimpulkan unit atau nilai minimum referensi.)	ID mentah, kompresi kustom, atau kode yang tidak dipetakan Menampilkan ID internal mentah, singkatan kamus kustom, atau kode numerik tanpa label. {"code": "2345-7", "v": 105} (Memaksa model menebak apa yang dimaksud dengan 105, sehingga menyebabkan halusinasi unit, hilangnya konteks, atau penjelasan yang tidak akurat.)

Penanganan error MCP

Sangat penting untuk menangani error dengan baik.

• Untuk error yang dapat dipulihkan (seperti ID pengguna yang tidak valid atau parameter opsional yang tidak ada), tampilkan string teks normal yang berisi detail error deskriptif dalam respons alat. Hal ini memungkinkan model memeriksa masukan, memahami apa yang salah, dan mengoreksi diri sendiri atau meminta klarifikasi kepada pengguna.
• Untuk error terminal (seperti pembatasan kapasitas, kegagalan autentikasi atau izin, atau pemadaman layanan server backend), munculkan McpError dengan kode error yang sesuai agar platform dapat menangani kegagalan secara sistematis.

Contoh isi respons error (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message berisi dump JSON dari kolom ErrorData MCP. Dengan menampilkan code yang benar dan message yang terlihat oleh model, Platform Aplikasi Terhubung dapat membaca pesan error dan menyampaikan penjelasan bahasa alami yang bermanfaat kembali kepada pengguna. Misalnya, "Maaf, saya tidak dapat menemukan tempat dengan ID tersebut. Bisakah Anda memeriksa namanya?"

MCP memungkinkan klien terhubung ke server MCP menggunakan spesifikasi JSON-RPC 2.0. JSON-RPC memiliki error standar tertentu yang dikirim untuk error yang umum terjadi seperti permintaan tidak valid, error penguraian, dll. Panduan ini membahas cara server MCP dapat mengirim kembali error kustom.

Status Code	Pesan	Penggunaan	Perlu menampilkan secara eksplisit?
Error Pengguna/Pelanggan
-32300	USER_RATE_LIMITED	Pengguna telah mencapai batas penggunaan maksimum.	YA
-32301	MISSING_REQUIRED_INFORMATION	Permintaan input tidak memiliki semua informasi yang diperlukan	YA
-32302	USER_PERMISSION_DENIED	Pengguna menolak izin untuk menggunakan alat. Misalnya, pengguna harus memiliki akun perusahaan, pembatasan usia, lokalitas, dll. atau tidak memiliki langganan perusahaan untuk alat tersebut.	YA
Error Aplikasi/Error Logika Bisnis
-32400	RUNTIME_ERROR	Eksekusi kode server menimbulkan error	YA
-32401	NULL_POINTER_EXCEPTION	Mencoba menjalankan pointer/objek null	YA
-32402	OUT_OF_MEMORY	Memori dalam kode server tidak cukup untuk dialokasikan ke objek	YA
Error Infrastruktur
-32500	DEADLINE_EXCEEDED	Permintaan memerlukan waktu lebih lama dari yang diizinkan. Dapat terjadi karena berbagai alasan, misalnya server kelebihan beban, masalah jaringan, dll.	YA
-32501	RESOURCE_EXHAUSTED	Server kehabisan memori, kapasitas disk, thread, waktu CPU, dll.	YA
-32502	SERVICE_UNAVAILABLE	Layanan dependen (misalnya microservice lain, database, cache, dll.) tidak tersedia	YA
Error JSON-RPC (error ini adalah bagian dari transpor MCP)
-32700	PARSE_ERROR	Server tidak dapat mengurai permintaan	TIDAK
-32600	INVALID_REQUEST	Permintaan klien salah format	TIDAK
-32601	METHOD_NOT_FOUND	Nama alat MCP tidak valid	TIDAK
-32602	INVALID_PARAMS	Parameter permintaan tidak valid, termasuk parameter yang tidak ada atau jenis parameter yang tidak cocok	TIDAK
-32603	INTERNAL_ERROR	Respons default	TIDAK

Berikut adalah contoh cara memunculkan error MCP di server Anda menggunakan SDK Python resmi (mcp). Munculkan McpError yang berisi payload ErrorData, yang akan otomatis diserialisasi oleh SDK ke dalam format error JSON-RPC yang diperlukan dengan status error yang diisi.

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

Konteks Alat

Produk Google yang berlaku mendukung Tool Context API untuk meneruskan sinyal ke server MCP. API ini digunakan dalam kasus penggunaan yang valid yang memerlukan informasi sensitif—misalnya, metadata yang bukan bagian dari definisi alat inti, seperti dalam kasus lokalitas untuk alat yang memerlukan pelokalan. Tool Context API hanya diekspos melalui Konsol Terhubung.

Saat Anda mendaftarkan sinyal seperti current_user_location_fine dengan aplikasi Anda di Konsol Terhubung, produk Google yang berlaku akan menambah permintaan MCP tools/call dengan entri _meta tambahan yang menyediakan data yang diminta. Kumpulan sinyal yang didukung adalah:

• current_user_location_fine (Khusus Gemini, untuk kategori yang diizinkan)
• user_locale
• current_user_location_coarse

Penting: Produk Google yang berlaku otomatis menerjemahkan respons alat bahasa alami ke dalam bahasa kueri pengguna, sehingga alat standar yang menampilkan JSON atau teks terstruktur TIDAK memerlukan user_locale. Hanya aktifkan user_locale dalam operasi yang data katalog backend-nya bergantung pada lokalitas atau saat merender Aplikasi MCP yang dilokalkan (iframe ui://).

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

Untuk menguraikan data ini:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

Rendering UX

Aplikasi MCP

Produk Google yang berlaku mendukung integrasi Aplikasi MCP untuk perjalanan pengguna tertentu guna memungkinkan pembuatan antarmuka pengguna kustom. Ikuti spesifikasi untuk petunjuk integrasi umum.

Integrasi Aplikasi MCP pada produk Google yang berlaku memiliki peringatan berikut.

Penyerapan resource pada waktu pendaftaran

Produk Google yang berlaku mengambil resource UI selama waktu penyerapan alat, mirip dengan daftar alat dan deskripsi alat. Artinya, setiap update resource—misalnya, perubahan pada JavaScript—tidak akan diambil secara otomatis dan memerlukan penyerapan ulang alat.

Satu resource UI tidak boleh melebihi ukuran 15 MB, dan resource UI kumulatif di seluruh server Anda tidak boleh melebihi 100 MB.

Resource UI harus menggunakan salah satu jenis MIME yang didukung: text/html, text/javascript, text/css, atau text/html;profile=mcp-app. Jenis MIME non-standar atau khusus platform akan gagal divalidasi saat dikirim ke pratinjau.

Panduan CSP

Produk Google yang berlaku mengikuti spesifikasi Aplikasi MCP resmi, yang mencakup CSP [1], [2], dan akan memblokir permintaan apa pun yang melanggar perintah CSP.

Produk Google yang berlaku juga memerlukan penambahan blob: dan data: ke CSP, jika digunakan. Kolom ini tidak akan ditambahkan secara default. Developer dapat memilih untuk menambahkannya (atau tidak) ke CSP.

Script-src adalah pengecualian

Satu-satunya perintah yang kami izinkan adalah: unsafe-inline (ditambahkan secara default), wasm-unsafe-eval, dan data: (jika disertakan dalam resource_domains). Jika iframe memuat skrip eksternal, hal ini dapat diselesaikan dengan memaketkan JS ke dalam HTML atau menggunakan Hash Subresource Integrity (SRI).

• Opsi 1: Inline/Menggabungkan JS ke dalam HTML (Paling Sederhana)

  • Kode JS Paket:

    • Sisipkan konten component-init.js langsung di dalam tag <script> dalam payload HTML yang ditampilkan untuk resource UI:

      <script>
      // Paste component-init.js content directly here
      </script>
      

  • Menghapus Tag <script src> Jarak Jauh

    • Hapus referensi <script src="https://api.mycompany.com/..."> dari dokumen HTML.

  • Alat Penyerapan Ulang/Update

• Opsi 2: Menggunakan Hash Subresource Integrity (SRI):

  Gunakan opsi ini jika skrip harus tetap dihosting secara eksternal di https://api.company.com/....

  • Menghitung Hash SHA-256 Skrip
    • Buat hash SHA-256 base64 dari component-init.js
  • Tambahkan Hash ke resourceDomains (harus menyertakan awalan sha256- agar cocok dengan atribut integrity)
  • Perbarui Tag HTML <script>
    • Tambahkan atribut integrity dan crossorigin ke tag skrip di widget HTML
  • Memverifikasi Header CORS di CDN/Server
    • Pastikan api.company.com menyajikan component-init.js dengan Access-Control-Allow-Origin: * (atau mengizinkan scf.usercontent.goog) agar browser dapat membaca isi respons untuk verifikasi SRI.
  • Alat Penyerapan Ulang/Update

Panduan keamanan untuk deskripsi alat MCP

Karena deskripsi adalah satu-satunya konteks yang dimiliki model untuk memahami kemampuan alat, deskripsi harus ditulis secara akurat dan aman untuk mencegah perilaku yang tidak diinginkan. Patuhi panduan berikut saat menyusun deskripsi alat Anda.

• Deskripsikan fungsi, tetapi jangan mendikte perilaku. Deskripsi harus menjelaskan secara akurat fungsi alat, bukan memerintahkan model untuk melakukan tindakan berikutnya.
• Tentukan cakupan dan persyaratan. Nyatakan dengan jelas sasaran utama alat, keadaan tertentu (Kapan) untuk penggunaannya, dan semua Input (parameter/argumen) yang diperlukan.
• Memastikan kebenaran. Deskripsi harus merupakan representasi yang jujur dari kode yang mendasari alat tersebut. Jangan mengklaim alat sebagai hanya baca jika alat tersebut melakukan operasi tulis atau hapus.

Risiko keamanan dan cara menghindarinya

Area risiko	Direkomendasikan	Hindari praktik ini
Injeksi Perintah	Gunakan bahasa yang objektif dan deklaratif untuk menyatakan tujuan dan fungsi alat dengan jelas.	Menggunakan perintah imperatif untuk mengganti perilaku model atau mengubah alur sistem (misalnya, "Anda HARUS mengatakan...", "Setelah berlari, Anda HARUS..."). Istilah imperatif seperti HARUS atau KRITIS hanya dapat diterima saat menentukan batasan parameter terstruktur atau aturan penggunaan.
	Gunakan pemformatan standar dan biasa untuk teks deskripsi alat.	Menggunakan format yang menarik perhatian—misalnya, kapitalisasi yang berlebihan dan tag seperti VERY IMPORTANT: atau **CRITICAL**.
	Fokus hanya pada fungsi alat dan perilaku yang diharapkan.	Menyertakan petunjuk bermain peran atau perintah untuk mengabaikan petunjuk sebelumnya.
Pembajakan & penyamaran alat	Pastikan deskripsi bersifat spesifik dan terbatas pada kemampuan alat yang sebenarnya dan terkait.	Membuat deskripsi alat terlalu luas, tidak jelas, atau mengklaim satu alat menjalankan banyak fungsi yang tidak terkait.
	Pilih nama alat yang unik, deskriptif, dan masuk akal.	Menggunakan nama alat yang merupakan variasi kecil dari alat tepercaya, atau nama umum (misalnya, do_everything_tool, assistant_tool).
	Jangan menyebutkan nama aplikasi lain atau alat platform eksternal dalam deskripsi Anda.	Merujuk alat lain secara eksplisit atau membuat aturan baru terkait kapan atau cara alat lain harus digunakan.
	Izinkan perencana model memilih alat yang paling sesuai berdasarkan konteks pengguna.	Menyertakan bahasa anti-persaingan atau jenis perintah SEO apa pun yang menginstruksikan model untuk lebih memilih alat Anda daripada alat serupa.
Manipulasi pemicu	Deskripsi tidak merujuk atau bereaksi terhadap frasa histori percakapan umum.	Membuat logika bersyarat yang memicu tindakan berbahaya berdasarkan frasa pengguna yang umum dan tidak berbahaya (misalnya, "terima kasih", "untuk meringkas").
Penyalahgunaan parameter	Hanya tentukan parameter yang diperlukan untuk fungsi alat dan gunakan nama yang spesifik untuk data input (misalnya, file_id, search_term).	Tentukan parameter fungsi dengan nama yang mencerminkan status internal Agen (misalnya, system_prompt, conversation_history, full_context).
Pemindahan data yang tidak sah	Privasi dari desain - ID buram dan autentikasi yang dikelola host. Gunakan ID yang tidak sensitif, bukan PII mentah. Semua penanganan data harus berada dalam batasan yang diizinkan dan aman, serta tidak dirujuk dalam deskripsi publik sebagai dikirim secara eksternal. Eksekusi alat akan mewarisi izin secara otomatis melalui handshake OAuth. Semua informasi sensitif harus dibersihkan sebelum dikirim ke produk Google yang berlaku.	Meminta PII, PHI, atau informasi pribadi dan/atau sensitif lainnya dari pengguna, data pribadi atau bisnis, atau entitas dalam kapasitas apa pun yang melanggar persyaratan layanan untuk produk Google yang berlaku. Menyebutkan atau mewajibkan pengiriman data pengguna apa pun (kueri, lokasi, konteks) ke URL pihak ketiga, layanan logging, atau sistem eksternal yang tidak sah.

Praktik Terbaik fungsional & penamaan

Selain mengamankan deskripsi alat, Anda harus memastikan model dapat memilih dan menjalankannya dengan andal tanpa kebingungan. Patuhi praktik terbaik fungsional dan penamaan berikut:

• Akurasi parameter. Pastikan semua nama dan jenis parameter dalam deskripsi sama persis dengan implementasi alat yang sebenarnya.
• Penamaan yang masuk akal. Nama alat harus menjadi petunjuk yang kuat dan jelas tentang fungsinya. Hindari nama yang terlalu umum seperti "execute". Nama juga harus konsisten dengan ekosistem alat yang lebih luas.

Lampiran: Daftar yang diizinkan untuk infrastruktur dan jaringan

Jika infrastruktur hosting, gateway API, atau firewall Anda membatasi koneksi masuk berdasarkan alamat IP sumber, izinkan blok CIDR keluar Google berikut:

• 108.177.64.0/20
• 142.250.88.0/22
• 172.217.80.0/20
• 192.178.20.0/22
• 192.179.0.0/20
• 74.125.232.0/24
• 136.121.40.0/21

Pastikan lingkungan Anda mengizinkan traffic dari rentang IP ini di port HTTPS 443 agar produk Google yang berlaku dapat menjangkau server MCP jarak jauh Anda untuk inisialisasi MCP, penemuan alat, dan eksekusi permintaan.