Mengonfigurasi Model Context Protocol

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menjelaskan cara mengonfigurasi Gateway API agar berfungsi sebagai server Model Context Protocol (MCP) jarak jauh.

Sebelum memulai

• Pastikan Anda memiliki spesifikasi OpenAPI 3.x yang valid untuk API Anda. MCP tidak didukung untuk OpenAPI 2.0.
• Pastikan Anda memahami dasar-dasar API Gateway.

Validasi konfigurasi

Saat Anda mengupload spesifikasi OpenAPI, Gateway API akan melakukan validasi berikut untuk konfigurasi MCP:

• Lokasi: Ekstensi x-google-mcp-tool hanya boleh ditentukan di tingkat operasi individual.
• Metode HTTP: Hanya operasi GET, POST, PUT, PATCH, dan DELETE yang dapat diekspos sebagai alat MCP.
• Nama Alat: Nama alat harus cocok dengan [A-Za-z0-9_.-]{1,128} dan unik di seluruh spesifikasi.
• Deskripsi: Setiap alat harus memiliki deskripsi yang tidak kosong (diambil dari deskripsi, ringkasan, atau penggantian operasi). Operasi tanpa deskripsi yang dapat diselesaikan akan ditolak.
• Keamanan: Jika mengonfigurasi autentikasi untuk tools/list, Anda harus memberi nama tepat satu skema keamanan JWT yang ditentukan di bagian components.securitySchemes. Keamanan kunci API tidak didukung untuk tools/list dalam Pratinjau Publik.

Model autentikasi

Gateway API menerapkan aturan autentikasi yang berbeda, bergantung pada metode MCP yang dipanggil:

• Siklus Proses Protokol: Metode initialize dan notifications/initialized bersifat tidak diautentikasi.
• Pemanggilan Alat (tools/call): Menggunakan kembali kebijakan autentikasi yang ditentukan untuk operasi pokok dalam spesifikasi OpenAPI Anda. Fungsi ini memberlakukan persyaratan kunci API atau JWT yang sama seperti memanggil endpoint REST secara langsung.
• Penemuan Alat (tools/list): Secara default, metode ini tidak diautentikasi. Namun, sebagai praktik terbaik keamanan, sangat disarankan untuk melindungi penemuan alat dengan mengaktifkan autentikasi untuk metode ini menggunakan tools-list.security. Jika memilih untuk mengaktifkan autentikasi, Anda harus menggunakan skema keamanan JWT. Autentikasi kunci API tidak didukung untuk tools/list.

Langkah-langkah untuk mengonfigurasi MCP

Ikuti langkah-langkah berikut untuk mengekspos API Anda sebagai alat MCP:

1. Mengidentifikasi operasi yang akan diekspos

Tinjau spesifikasi OpenAPI Anda dan tentukan operasi mana yang harus tersedia untuk agen AI.

2. Memperbarui spesifikasi OpenAPI

Anda dapat mengaktifkan MCP secara global untuk semua operasi yang memenuhi syarat, atau mengonfigurasinya berdasarkan per operasi.

Pengaktifan global

Aktifkan MCP secara global dengan menambahkan kolom mcp ke x-google-api-management di tingkat dokumen:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Catatan: Pastikan operasi Anda telah dikonfigurasi backend-nya (baik menggunakan x-google-backend di tingkat operasi atau menggunakan default global) agar memenuhi syarat sebagai alat MCP.

Jika diaktifkan secara global, semua operasi yang memenuhi syarat (berdasarkan metode dan jalur HTTP) akan diekspos sebagai alat MCP. Secara default, nama alat adalah operationId operasi, dan deskripsinya adalah deskripsi atau ringkasan operasi.

Konfigurasi per operasi

Anda dapat mengganti setelan global atau mengekspos operasi secara selektif menggunakan x-google-mcp-tool:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

Anda juga dapat membatalkan operasi saat diaktifkan secara global dengan menyetel x-google-mcp-tool: false.

3. Autentikasi tools/list (Direkomendasikan)

Secara default, metode tools/list (yang menghitung alat yang tersedia) tidak diautentikasi. Sebagai praktik terbaik keamanan, sebaiknya terapkan autentikasi dengan mengonfigurasi tools-list.security di bagian x-google-api-management/mcp. Anda harus menggunakan skema JWT; kunci API tidak didukung untuk metode ini.

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

Catatan: Mengonfigurasi ekstensi mcp sebagai objek (misalnya, untuk mengaktifkan autentikasi untuk tools/list) juga mengaktifkan MCP secara global untuk semua operasi yang memenuhi syarat. Jika Anda ingin mengonfigurasi keamanan tools/list, tetapi tidak ingin mengekspos semua operasi yang memenuhi syarat, Anda harus secara eksplisit menonaktifkan operasi tersebut dengan menyetel x-google-mcp-tool: false.

4. Buat dan deploy konfigurasi API

Buat konfigurasi API dari spesifikasi yang dianotasi dan deploy ke gateway menggunakan alur standar. Lihat Men-deploy API ke gateway untuk mengetahui detailnya.

5. Memverifikasi dukungan MCP

Setelah di-deploy, Anda dapat memverifikasi bahwa gateway melayani permintaan MCP.

Jabat tangan

Mengirim permintaan inisialisasi untuk menetapkan versi dan kemampuan protokol:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Catatan: Klien harus mengirim header MCP-Protocol-Version pada setiap permintaan setelah inisialisasi. Jika header tidak ada, gateway akan kembali ke versi 2025-03-26.

Mengonfirmasi handshake

Mengonfirmasi inisialisasi. Gateway merespons dengan HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Menemukan alat

Mencantumkan alat yang tersedia:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Cara argumen dipetakan ke permintaan REST

Argumen yang diteruskan ke alat dipetakan ke permintaan REST pokok berdasarkan spesifikasi OpenAPI:

• Parameter jalur dan kueri: Menjadi properti tingkat teratas dalam objek arguments, yang dikelompokkan berdasarkan nama parameter OpenAPI-nya.
• Isi permintaan: Disusun bertingkat di bawah satu properti bernama body. Misalnya, untuk membuat resource, Anda meneruskan {"body": {"fieldName": "value"}}.
• Header: Juga menjadi properti tingkat teratas. Gateway menyisipkannya sebagai header HTTP standar dalam panggilan backend.

Catatan: Anda tidak dapat mengikat parameter ke header sistem yang dicadangkan atau header yang diawali dengan x-google-.

Permintaan backend yang ditranskode tidak dapat dibedakan dari permintaan REST langsung ke layanan backend Anda. Layanan backend tidak dapat membedakan secara terprogram antara panggilan REST langsung dan panggilan yang ditranskode dari MCP.

Memanggil alat

Panggil alat tertentu. Pastikan Anda menyertakan token autentikasi yang diperlukan jika operasi REST yang mendasarinya memerlukannya:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Kemampuan observasi

Permintaan MCP menghasilkan metrik dan log Gateway API standar. Anda dapat membedakan traffic MCP dari traffic REST standar dengan memeriksa jalur permintaan (biasanya diakhiri dengan /mcp) atau dengan mengonfigurasi metrik kustom.

Memecahkan masalah kegagalan MCP

MCP membedakan antara kegagalan transportasi dan kegagalan protokol. Gateway menampilkan HTTP 200 dengan objek error JSON-RPC untuk error protokol dan aplikasi, karena respons non-200 dapat menyebabkan banyak klien MCP gagal di lapisan transport.

Tabel berikut menjelaskan gejala dan perbaikan umum:

Gejala	Kode JSON-RPC	Status HTTP	Arti dan Perbaikan Umum
Method Not Allowed	t/a	405	Permintaan non-POST mencapai /mcp. Hanya HTTP POST yang didukung.
Error penguraian JSON	-32700	400	Isi permintaan bukan JSON yang valid.
Metode atau ID Tidak Ada/Tidak Valid	-32600	200	Isinya adalah JSON yang valid, tetapi bukan permintaan JSON-RPC yang valid. Periksa kolom wajib diisi (jsonrpc, method, id).
Metode tidak didukung	-32601	200	Metode ini berada di luar cakupan yang didukung (misalnya, ping).
Versi protokol tidak didukung	-32602	200	protocolVersion menyebutkan versi yang tidak didukung gateway.
Versi Protokol Tidak Ada	-32602	200	Parameter initialize menghilangkan protocolVersion atau bukan string.
Alat tidak dikenal	-32602	200	Nama alat tidak ditemukan. Hapus cache klien atau verifikasi deployment.
Argumen alat tidak valid	-32602	200	Argumen tidak ada atau tidak valid. Verifikasi penataan kunci body.
Isi terlalu besar	-32000	200	Payload respons melebihi batas ukuran.
Isi transportasi terlalu besar	t/a	413	Isi permintaan HTTP mentah melebihi batas transportasi gateway.
Error server	-32000	200	Respons backend tidak dapat diuraikan. Periksa log.
Tidak Sah / Dilarang	t/a	401/403	Kegagalan autentikasi. Respons membawa header WWW-Authenticate yang mengarah ke metadata resource yang dilindungi.

Error aplikasi backend biasanya muncul sebagai respons JSON-RPC yang berhasil (HTTP 200) dengan result.isError: true yang berisi isi error backend.

Langkah berikutnya

• Ringkasan Model Context Protocol
• Ekstensi OpenAPI 3.x
• Batasan fitur OpenAPI 3.x