Mengonfigurasi Model Context Protocol

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 diselesaikan ke deskripsi yang tidak kosong (diambil dari deskripsi, ringkasan, atau penggantian operasi). Operasi tanpa deskripsi yang dapat diselesaikan akan ditolak.
• Keamanan: Jika Anda mengonfigurasi autentikasi untuk tools/list, Anda harus memberi nama tepat 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 teratas spesifikasi.

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

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

4. Membuat dan men-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

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

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

Menemukan alat

Buat 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 memetakan argumen 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 dikunci 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.

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

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

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:

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