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 untuk bertindak 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 Gateway API.

Validasi konfigurasi

Saat Anda mengupload spesifikasi OpenAPI, Gateway API 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 di-resolve akan ditolak.
• Keamanan: Jika Anda mengonfigurasi autentikasi untuk tools/list, Anda harus memberi nama persis satu skema keamanan yang ditentukan di bagian components.securitySchemes. Skema ini dapat berupa skema JWT atau skema kunci API. Jika menggunakan skema JWT, Anda juga harus menamainya dalam persyaratan security tingkat atas spesifikasi.

Model autentikasi

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

• Siklus Proses Protokol: Metode initialize dan notifications/initialized tidak diautentikasi.
• Pemanggilan Alat (tools/call): Menggunakan kembali kebijakan autentikasi yang ditentukan untuk operasi yang mendasarinya dalam spesifikasi OpenAPI Anda. Library ini menerapkan 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, sebaiknya Anda melindungi penemuan alat dengan mengaktifkan autentikasi untuk metode ini menggunakan tools-list.security. Anda dapat mengautentikasi tools/list dengan JWT atau kunci API.

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 per operasi.

Pemberdayaan 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 memiliki backend yang dikonfigurasi (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 memilih untuk tidak mengaktifkan operasi saat diaktifkan secara global dengan menetapkan x-google-mcp-tool: false.

3. Mengautentikasi tools/list (Direkomendasikan)

Secara default, metode tools/list (yang menghitung alat yang tersedia) tidak diautentikasi. Sebagai praktik terbaik keamanan, sebaiknya Anda menerapkan autentikasi dengan mengonfigurasi tools-list.security di bagian x-google-api-management.mcp. Anda dapat memberi nama skema JWT atau skema kunci API.

Contoh berikut memerlukan JWT:

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

Contoh berikut memerlukan kunci API. Klien harus mengirim kunci di header HTTP x-api-key; tools/list tidak membaca kunci API dari parameter kueri. Permintaan tanpa kunci yang valid akan menerima error JSON-RPC dan tidak ada daftar alat. Untuk mempelajari cara membuat kunci API, lihat Menggunakan kunci API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

Catatan: Mengonfigurasi ekstensi mcp sebagai objek (misalnya, untuk mengaktifkan autentikasi untuk tools/list) juga akan 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 memilih untuk tidak mengikutsertakan operasi tersebut dengan menetapkan x-google-mcp-tool: false.

4. Membuat dan men-deploy konfigurasi API

Buat konfigurasi API dari spesifikasi yang telah dianotasi dan deploy ke gateway menggunakan alur standar. Lihat Men-deploy API ke gateway untuk mengetahui detailnya. Untuk mengubah alat nanti, lihat Memperbarui alat MCP yang terekspos.

5. Memverifikasi dukungan MCP

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

Handshake

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

Konfirmasi handshake

Konfirmasi 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"}'

Temukan alat

Membuat daftar alat yang tersedia. Jika Anda mengonfigurasi tools-list.security, tambahkan kredensial yang cocok, seperti header Authorization: Bearer untuk JWT atau header x-api-key untuk kunci API:

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 yang mendasarinya berdasarkan spesifikasi OpenAPI:

• Parameter jalur dan kueri: Menjadi properti tingkat teratas dalam objek arguments, yang diberi kunci berdasarkan nama parameter OpenAPI-nya.
• Isi permintaan: Bertingkat di bawah satu properti bernama body. Misalnya, untuk membuat resource, Anda meneruskan {"body": {"fieldName": "value"}}.
• Header: Juga menjadi properti tingkat teratas. Gateway memasukkannya 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 di-transcoding 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

Memanggil 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"}
  }
}'

Mengupdate alat MCP yang terekspos

Konfigurasi API di Gateway API tidak dapat diubah, sehingga Anda tidak dapat mengubah definisi API dalam konfigurasi API yang ada. Akibatnya, respons tools/list bersifat statis untuk setiap konfigurasi API yang di-deploy.

Untuk menambahkan, menghapus, mengganti nama, atau mengupdate alat MCP yang terekspos atau setelan keamanan tools/list, buat konfigurasi API baru dan deploy ke gateway Anda:

1. Perbarui spesifikasi OpenAPI 3.x Anda, termasuk operasi, nilai operationId, ringkasan, parameter, serta ekstensi x-google-api-management.mcp dan x-google-mcp-tool.

2. Buat konfigurasi API baru dengan ID konfigurasi API baru:

   gcloud api-gateway api-configs create NEW_CONFIG_ID \
       --api=API_ID \
       --openapi-spec=API_DEFINITION \
       --project=PROJECT_ID \
       --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   Ganti kode berikut:

   • NEW_CONFIG_ID: ID baru untuk konfigurasi API yang diupdate
   • API_ID: ID API Gateway API
   • API_DEFINITION: jalur ke spesifikasi OpenAPI 3.x yang telah diupdate
   • PROJECT_ID: Project ID Google Cloud Anda
   • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan yang digunakan untuk menandatangani token bagi backend dengan autentikasi yang dikonfigurasi. Hapus flag ini jika tidak ada backend Anda yang memerlukan autentikasi.

   Untuk mengetahui informasi selengkapnya, lihat Membuat konfigurasi API.

3. Update setiap gateway yang menyajikan API untuk menggunakan konfigurasi API baru:

   gcloud api-gateway gateways update GATEWAY_ID \
       --api=API_ID \
       --api-config=NEW_CONFIG_ID \
       --location=GCP_REGION \
       --project=PROJECT_ID

   Ganti kode berikut:

   • GATEWAY_ID: ID gateway yang akan diupdate
   • GCP_REGION: region tempat gateway di-deploy

   Untuk mengetahui informasi selengkapnya, lihat Memperbarui gateway.

4. Panggil tools/list untuk memeriksa set alat yang diperbarui. Untuk contoh permintaan, lihat Menemukan alat.

5. Setelah tidak ada gateway yang menggunakan konfigurasi API sebelumnya, hapus konfigurasi API yang digantikan:

   gcloud api-gateway api-configs delete OLD_CONFIG_ID \
       --api=API_ID \
       --project=PROJECT_ID

   Ganti OLD_CONFIG_ID dengan ID konfigurasi API yang digantikan. Jangan hapus konfigurasi API saat gateway masih menggunakannya; jika konfigurasi API baru Anda mengganti nama atau menghapus metrik kuota, gateway yang masih menyajikan konfigurasi API lama dapat menampilkan error HTTP 500 hingga diupdate (lihat Kuota berlaku untuk seluruh API). Untuk mengetahui informasi selengkapnya, lihat Menghapus konfigurasi API.

Perhatikan perilaku peluncuran dan klien berikut saat Anda mengupdate alat MCP:

• Peluncuran tanpa periode nonaktif: Gateway API mengupdate gateway tanpa periode nonaktif. Saat konfigurasi API baru diterapkan, beberapa permintaan mungkin akan menjangkau konfigurasi API sebelumnya untuk sementara. Jika API Anda di-deploy di beberapa gateway atau region, update setiap gateway secara terpisah.
• Cache alat klien: Karena Gateway API menyajikan MCP melalui transport HTTP stateless, gateway tidak memunculkan notifikasi notifications/tools/list_changed. Setelah update gateway selesai, klien MCP yang meng-cache definisi alat harus memanggil tools/list lagi untuk menemukan alat yang diupdate.
• Batas konfigurasi API: Setiap API dibatasi hingga 100 konfigurasi API, jadi hapus konfigurasi API yang digantikan setelah mengupdate gateway Anda. Buat konfigurasi API satu per satu; jika Anda memulai konfigurasi API kedua untuk API yang sama sebelum konfigurasi pertama selesai, salah satu atau kedua konfigurasi tersebut mungkin tidak dapat digunakan oleh gateway. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas.

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 transpor 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	Isi adalah JSON yang valid, tetapi bukan permintaan JSON-RPC yang valid. Periksa kolom wajib diisi (jsonrpc, method, id).
Metode tidak didukung	-32601	200	Metode berada di luar cakupan yang didukung (misalnya, ping).
Versi protokol tidak didukung	-32602	200	protocolVersion memberi nama 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 dalam konfigurasi API yang di-deploy. Muat ulang cache alat klien, atau lihat Memperbarui alat MCP yang terekspos.
Argumen alat tidak valid	-32602	200	Argumen tidak ada atau tidak valid. Verifikasi penyusunan bertingkat kunci body.
Isi terlalu besar	-32000	200	Payload respons melebihi batas ukuran.
Isi transport terlalu besar	t/a	413	Isi permintaan HTTP mentah melebihi batas transportasi gateway.
Error server	-32000	200	Respons backend tidak dapat diurai. Periksa log.
Tidak Diizinkan/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