API Gateway:Referensi field konfigurasi HTTP ke MCP

Konfigurasi server

Konfigurasi tools yang diizinkan

Konfigurasi tool HTTP ke MCP

Menentukan skema autentikasi (server.securitySchemes)

Tentukan skema autentikasi yang dapat digunakan kembali di tingkat server. Tools mereferensikan skema ini untuk melakukan autentikasi dengan API HTTP backend.

Field konfigurasi (server.securitySchemes[]):

Contoh (server.securitySchemes):

server:
  name: my-api-server
  securitySchemes:
    - id: MyBasicAuth
      type: http
      scheme: basic
      defaultCredential: "admin:secretpassword" # Username dan password default
    - id: MyBearerToken
      type: http
      scheme: bearer
      defaultCredential: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # Bearer Token default
    - id: MyApiKeyInHeader
      type: apiKey
      in: header
      name: X-Custom-API-Key # API key berada di header bernama X-Custom-API-Key
      defaultCredential: "abcdef123456" # API key default
    - id: MyApiKeyInQuery
      type: apiKey
      in: query
      name: "api_token" # API key berada di parameter kueri bernama api_token
      defaultCredential: "uvwxyz789012"

Menerapkan skema autentikasi dalam tools

Setelah mendefinisikan server.securitySchemes, referensikan skema tersebut dalam field requestTemplate.security masing-masing tool menggunakan id untuk menentukan cara MCP Server melakukan autentikasi dengan API HTTP backend.

• tools[].requestTemplate.security.id: Mereferensikan id skema autentikasi yang didefinisikan di server.securitySchemes.

• tools[].requestTemplate.security.credential: Opsional. Jika disediakan, field ini mengganti defaultCredential dalam skema yang direferensikan. Hal ini memungkinkan Anda menggunakan kredensial berbeda untuk tool tertentu, meskipun menggunakan mekanisme autentikasi yang sama.

Contoh:

tools:
  - name: get-user-details
    # ... konfigurasi tool lainnya ...
    requestTemplate:
      url: "https://api.example.com/users/{{.args.userId}}"
      method: GET
      security:
        id: MyBearerToken # Menggunakan skema MyBearerToken yang didefinisikan di atas
        # credential: "override_token_for_this_tool" # Opsional: Mengganti token default untuk tool ini
  # ...
  - name: update-inventory
    # ... konfigurasi tool lainnya ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # Menggunakan skema MyApiKeyInHeader
        # Tool ini akan menggunakan defaultCredential yang didefinisikan di MyApiKeyInHeader

Autentikasi passthrough

Autentikasi passthrough memungkinkan kredensial yang diberikan oleh MCP Client diteruskan melalui MCP Server untuk mengautentikasi panggilan ke API HTTP backend.

Metode konfigurasi:

1. Pastikan skema autentikasi yang relevan telah didefinisikan di server.securitySchemes. Ini mencakup skema yang digunakan client untuk terhubung ke MCP Server dan skema yang digunakan MCP Server untuk terhubung ke API HTTP backend.

2. Konfigurasikan autentikasi tingkat tool (tools[].security): Untuk tool yang memerlukan credential passthrough, konfigurasikan field security:

   • id: Mereferensikan skema autentikasi yang didefinisikan di server.securitySchemes yang digunakan untuk autentikasi antara MCP Client dan MCP Server. Plugin mengekstraksi kredensial dari permintaan client berdasarkan skema ini dan menghapus kredensial tersebut dari permintaan asli.

   • passthrough: true: Mengaktifkan autentikasi passthrough.

3. Konfigurasikan autentikasi templat permintaan (tools[].requestTemplate.security): Konfigurasikan field security dalam requestTemplate tool:

   • id: Mereferensikan skema autentikasi yang didefinisikan di server.securitySchemes yang digunakan untuk autentikasi antara MCP Server dan API HTTP backend.

   • Ketika tools[].security.passthrough diatur ke true, kredensial yang diekstraksi dari client diterapkan pada panggilan ke API HTTP backend sesuai dengan skema requestTemplate.security ini.

Contoh:

Asumsikan bahwa client MCP menggunakan Bearer Token untuk memanggil MCP Server, dan MCP Server perlu menggunakan API key untuk memanggil API HTTP backend.

server:
  name: product-api-server
  securitySchemes:
    - id: ClientSideBearer # Client menggunakan Bearer Token
      type: http
      scheme: bearer
    - id: BackendApiKey    # API backend menggunakan X-API-Key
      type: apiKey
      in: header
      name: X-API-Key
      # defaultCredential: "optional_default_backend_key"

tools:
  - name: get-product-securely
    description: "Dapatkan informasi produk (passthrough aman)"
    security: # Konfigurasi autentikasi Client -> MCP Server
      id: ClientSideBearer # MCP Server mengharapkan client menggunakan skema ini dan akan mencoba mengekstraksi jenis kredensial ini
      passthrough: true   # Izinkan credential passthrough
    args:
      - name: product_id
        description: "ID Produk"
        type: string
        required: true
    requestTemplate:
      security: # Konfigurasi autentikasi MCP Server -> API HTTP backend
        id: BackendApiKey # API backend memerlukan skema ini. Kredensial passthrough akan diterapkan sesuai skema ini.
      url: "https://api.example.com/products/{{.args.product_id}}"
      method: GET

Alur kerja

1. Client MCP mengirim permintaan ke tool get-product-securely di MCP Server. Permintaan membawa Bearer <client_token> di header Authorization.

2. MCP Server mengidentifikasi bahwa client menggunakan Bearer Token berdasarkan tools[].security (id: ClientSideBearer). Server mengekstraksi <client_token> dari permintaan dan menghapus header Authorization asli.

3. Karena passthrough: true diatur, <client_token> yang diekstraksi ditandai sebagai kredensial passthrough.

4. MCP Server bersiap memanggil API HTTP backend. Server memeriksa requestTemplate.security (id: BackendApiKey).

5. Karena passthrough diaktifkan, MCP Server menggunakan <client_token> yang diekstraksi sebelumnya sebagai nilai kredensial. Server menambahkan nilai ini ke permintaan ke https://api.example.com/products/... sebagai header HTTP bernama X-API-Key, sesuai dengan skema BackendApiKey.

6. API HTTP backend menerima permintaan dengan header X-API-Key yang diatur ke <client_token>.

Pemecahan masalah: Kredensial passthrough tidak berlaku

Jika kredensial yang diteruskan dari client tidak diterapkan pada panggilan API HTTP backend, dan MCP Server kembali menggunakan defaultCredential yang didefinisikan di server.securitySchemes, periksa item konfigurasi berikut:

• Pastikan passthrough diaktifkan di tingkat tool: Periksa bahwa tools[].security.passthrough diatur ke true untuk tool tertentu. Passthrough hanya berlaku untuk tool tempat dikonfigurasi secara eksplisit; bukan pengaturan global.

• Pastikan skema autentikasi yang direferensikan sesuai dengan jenis kredensial yang dikirim oleh client atau SDK: Periksa bahwa skema yang direferensikan oleh tools[].security.id (misalnya, ClientSideBearer) sesuai dengan jenis kredensial aktual yang dikirim oleh client atau SDK. Jika skema mengharapkan Bearer Token tetapi client mengirim jenis kredensial berbeda, MCP Server tidak dapat mengekstraksi kredensial passthrough dengan benar.

• Pastikan defaultCredential adalah kredensial yang valid dan dapat digunakan: Periksa nilai defaultCredential yang dikonfigurasi di bawah skema yang sesuai di server.securitySchemes. Nilai ini harus merupakan kredensial valid yang diterima oleh API HTTP backend (misalnya, JWT yang diformat dengan baik untuk skema Bearer Token), bukan placeholder templat. Ketika passthrough tidak berlaku, MCP Server kembali menggunakan defaultCredential untuk panggilan backend. Jika defaultCredential tidak valid, autentikasi terhadap API HTTP backend gagal.

Jenis posisi yang didukung

• query: Parameter dilewatkan sebagai parameter kueri di URL.

• path: Parameter menggantikan placeholder path di URL, seperti {petId} di /pet/{petId}.

• header: Parameter dilewatkan dalam header HTTP.

• cookie: Parameter dilewatkan sebagai cookie.

• body: Parameter dilewatkan dalam body permintaan. Secara otomatis diformat sebagai JSON atau form berdasarkan tipe konten.

Contoh

args:
  - name: petId
    description: "ID Hewan Peliharaan"
    type: string
    required: true
    position: path
  - name: token
    description: "Token autentikasi"
    type: string
    required: true
    position: header
  - name: sessionId
    description: "ID Sesi"
    type: string
    position: cookie
  - name: limit
    description: "Jumlah hasil yang dikembalikan"
    type: integer
    default: 10
    position: query
  - name: tags
    description: "Daftar tag"
    type: array
    position: body

Dalam contoh di atas:

• petId menggantikan placeholder {petId} di URL.

• token ditambahkan ke permintaan sebagai header HTTP.

• sessionId ditambahkan ke permintaan sebagai cookie.

• limit ditambahkan ke URL sebagai parameter kueri.

• tags ditambahkan ke body permintaan.

Hubungan dengan opsi penanganan parameter batch

Parameter dengan position yang ditentukan tidak terpengaruh oleh opsi batch (argsToJsonBody, argsToUrlParam, argsToFormBody). Opsi batch hanya berlaku untuk parameter tanpa position yang ditentukan.

Sebagai contoh, jika Anda menggunakan position dan argsToJsonBody secara bersamaan:

• Parameter dengan position: query ditambahkan ke string kueri URL.

• Parameter dengan position: header ditambahkan ke header HTTP.

• Parameter dengan position: path menggantikan placeholder di URL.

• Parameter dengan position: cookie ditambahkan sebagai cookie.

• Parameter dengan position: body ditambahkan ke body permintaan JSON.

• Parameter tanpa position yang ditentukan ditambahkan ke body permintaan JSON oleh argsToJsonBody.

Selain itu, jika Anda secara eksplisit menentukan body di requestTemplate, semua parameter dengan position: body diabaikan untuk menghindari konflik.

Templat permintaan

Anda dapat menggunakan templat permintaan untuk membuat URL, header, dan body permintaan HTTP:

• Untuk mengakses nilai konfigurasi, gunakan .config.fieldName.

• Untuk mengakses parameter tool, gunakan .args.parameterName.

Templat respons

Anda dapat menggunakan templat respons untuk mengubah respons HTTP menjadi format yang sesuai untuk konsumsi AI:

• Untuk mengakses field respons JSON, gunakan sintaksis path GJSON.

• Anda dapat menggunakan fungsi templat seperti add, upper, dan lower.

• Anda dapat menggunakan struktur kontrol seperti if dan range.

GJSON Template mencakup semua fungsi Sprig (70+ fungsi setara dengan templat Helm):

Fungsi Sprig umum meliputi:

• Manipulasi string: trim, upper, lower, replace, plural, nospace

• Operasi matematika: add, sub, mul, div, max, min

• Pemformatan tanggal: now, date, dateInZone, dateModify

• Operasi daftar: list, first, last, uniq, sortAlpha

• Operasi kamus: dict, get, set, hasKey, pluck

• Kontrol alur: ternary, default, empty, coalesce

• Konversi tipe: toString, toJson, toPrettyJson, toRawJson

• Enkode/Dekode: b64enc, b64dec, urlquery, urlqueryescape

• Generasi UUID: uuidv4

GJSON Template mencakup set fungsi yang sama dengan fungsi templat Helm.

Sintaksis path GJSON

GJSON menyediakan kemampuan kueri JSON yang kuat:

• Notasi titik: address.city

• Indeks array: users.0.name

• Iterasi array: users.#.name

• Filter array: users.#(age>=30)#.name

• Pengubah: users.@reverse.#.name

• Path ganda: {name:users.0.name,count:users.#}

• Karakter escape: path.with\.dot

Untuk kueri yang lebih kompleks, Anda dapat menggunakan fungsi gjson:

<!-- Gunakan fungsi gjson untuk kueri kompleks -->
Active users: {{gjson "users.#(active==true)#.name"}}

<!-- Filter array dengan beberapa kondisi -->
Active developers over 30: {{gjson "users.#(active==true && age>30)#.name"}}

<!-- Menggunakan pengubah -->
Usernames (reversed): {{gjson "users.@reverse.#.name"}}

<!-- Iterasi hasil yang difilter -->
Administrators:
{{range $user := gjson "users.#(roles.#(==admin)>0)#"}}
 - {{$user.name}} ({{$user.age}})
{{end}}

Sintaksis path lengkap didokumentasikan dalam dokumentasi GJSON.

Contoh penggunaan server MCP bawaan: Mengonfigurasi quark-search

server:
  name: "quark-search"
  config:
    apiKey: "xxxx"

Menggunakan server MCP bawaan `quark-search` di Higress. Hanya nama server dan konfigurasi yang diperlukan seperti API key yang dibutuhkan — tools telah ditentukan sebelumnya.

Contoh dasar: Mengubah API AMAP

server:
  name: HTTP-amap-server
  config:
    apiKey: your-api-key-here
tools:
  - name: maps-geo
    description: "Mengonversi alamat terstruktur yang detail menjadi koordinat lintang dan bujur. Mendukung resolusi landmark, tempat wisata, dan nama bangunan menjadi koordinat."
    args:
      - name: address
        description: "Alamat terstruktur yang akan diresolusi."
        type: string
        required: true
      - name: city
        description: "Kota yang akan dikueri."
        type: string
        required: false
      - name: output
        description: "Format output."
        type: string
        enum: ["json", "xml"]
        default: "json"
    requestTemplate:
      url: "https://HTTPapi.amap.com/v3/geocode/geo"
      method: GET
      argsToUrlParam: true
      headers:
        - key: x-api-key
          value: "{{.config.apiKey}}"
    responseTemplate:
      body: |
        # Informasi Geocoding
        {{- range $index, $geo := .geocodes }}
        ## Lokasi {{add $index 1}}

        - **Negara**: {{ $geo.country }}
        - **Provinsi**: {{ $geo.province }}
        - **Kota**: {{ $geo.city }}
        - **Kode Kota**: {{ $geo.citycode }}
        - **Distrik**: {{ $geo.district }}
        - **Jalan**: {{ $geo.street }}
        - **Nomor Jalan**: {{ $geo.number }}
        - **Adcode**: {{ $geo.adcode }}
        - **Lokasi**: {{ $geo.location }}
        - **Level**: {{ $geo.level }}
        {{- end }}

Konfigurasi ini mengubah API geocoding AMAP menjadi tool yang dapat dipanggil AI. Ketika AI memanggil tool ini:

1. Membuat permintaan API menggunakan parameter alamat dan kota yang diberikan.

2. Memanggil API AMAP.

3. Mengubah respons JSON menjadi format Markdown yang mudah dibaca.

4. Mengembalikan hasil yang diformat ke asisten AI.

Contoh lanjutan: Penanganan respons kompleks dengan logika kondisional

server:
  name: weather-api-server
  config:
    apiKey: your-weather-api-key
tools:
  - name: get-weather
    description: "Mendapatkan prakiraan cuaca untuk kota yang ditentukan."
    args:
      - name: city
        description: "Nama kota"
        type: string
        required: true
      - name: days
        description: "Jumlah hari (1-7)"
        type: integer
        required: false
        default: 3
      - name: include_hourly
        description: "Menentukan apakah akan menyertakan prakiraan per jam."
        type: boolean
        default: true
    requestTemplate:
      url: "https://api.weatherapi.com/v1/forecast.json"
      method: GET
      argsToUrlParam: true
      headers:
        - key: x-api-key
          value: "{{.config.apiKey}}"
    responseTemplate:
      body: |
        # Prakiraan Cuaca {{.location.name}}, {{.location.country}}

        **Suhu Saat Ini**: {{.current.temp_c}}°C
        **Terasa Seperti**: {{.current.feelslike_c}}°C
        **Kondisi**: {{.current.condition.text}}
        **Kelembapan**: {{.current.humidity}}%
        **Kecepatan Angin**: {{.current.wind_kph}} km/jam

        ## Prakiraan Mendatang
        {{range $index, $day := .forecast.forecastday}}
        ### {{$day.date}} ({{dateFormat "Monday" $day.date_epoch | title}})

        {{if gt $day.day.maxtemp_c 30}}**Peringatan suhu tinggi!**{{end}}
        {{if lt $day.day.mintemp_c 0}}**Peringatan suhu rendah!**{{end}}

        - **Suhu Maksimum**: {{$day.day.maxtemp_c}}°C
        - **Suhu Minimum**: {{$day.day.mintemp_c}}°C
        - **Kemungkinan Hujan**: {{$day.day.daily_chance_of_rain}}%
        - **Kondisi**: {{$day.day.condition.text}}

        #### Prakiraan Per Jam
        {{range $hour := slice $day.hour 6 24 3}}
        - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
        {{end}}
        {{end}}
```<p>Contoh ini menunjukkan cara:</p><ul><li><p>Menggunakan pernyataan kondisional (<code data-tag="code" dir="auto" id="8a2cd16431wep">if

Contoh ini menunjukkan:

• Menggunakan pernyataan kondisional (if) untuk memberikan peringatan suhu.

• Menggunakan fungsi pemformatan tanggal (dateFormat) untuk memformat tanggal.

• Menggunakan irisan array (slice) untuk memilih data cuaca pada waktu tertentu.

• Menggunakan loop bersarang untuk menjelajahi data cuaca di beberapa hari dan periode waktu.

Contoh penggunaan prependBody dan appendBody: Transformasi OpenAPI

Gunakan prependBody dan appendBody untuk menambahkan konteks di sekitar respons API asli. Ini berguna untuk transformasi OpenAPI di mana Anda mempertahankan JSON mentah tetapi menambahkan penjelasan field untuk asisten AI.

server:
  name: product-api-server
  config:
    apiKey: your-api-key-here
tools:
  - name: get-product
    description: "Dapatkan detail produk"
    args:
      - name: product_id
        description: "ID Produk"
        type: string
        required: true
    requestTemplate:
      url: "https://api.example.com/products/{{.args.product_id}}"
      method: GET
      headers:
        - key: Authorization
          value: "Bearer {{.config.apiKey}}"
    responseTemplate:
      prependBody: |
        # Informasi Produk

        Berikut adalah detail produk, dikembalikan dalam format JSON. Deskripsi field:

        - **id**: Identifier unik produk
        - **name**: Nama produk
        - **description**: Deskripsi produk
        - **price**: Harga produk (USD)
        - **category**: Kategori produk
        - **inventory**: Informasi inventaris
        - **quantity**: Jumlah stok saat ini
        - **warehouse**: Lokasi gudang
        - **ratings**: Daftar rating pengguna
        - **score**: Rating (1-5)
        - **comment**: Konten komentar
      appendBody: |

        Anda dapat menggunakan informasi ini untuk memahami detail produk, harga, status inventaris, dan ulasan pengguna.

Contoh ini menunjukkan cara:

• Menggunakan prependBody untuk menambahkan deskripsi field sebelum respons JSON asli.

• Menggunakan appendBody untuk menambahkan saran penggunaan di akhir respons.

• Mempertahankan respons JSON asli agar asisten AI dapat langsung mengakses semua data.

Informasi API saya

[Jelaskan API Anda di sini, termasuk endpoint, parameter, dan format respons, atau tempel spesifikasi Swagger/OpenAPI.]

Berdasarkan informasi di atas, hasilkan konfigurasi lengkap yang mencakup:
1. Nama deskriptif dan konfigurasi server yang sesuai.
2. Definisi untuk semua parameter yang diperlukan, dengan deskripsi jelas dan tipe, nilai wajib/default yang sesuai.
3. Metode pengiriman parameter paling sesuai (argsToUrlParam, argsToJsonBody, argsToFormBody, atau body kustom).
4. responseTemplate yang mengubah respons API menjadi format yang mudah dibaca dan sesuai untuk konsumsi AI.

Spesifikasi pengisian tools[].args dalam YAML

Parameter tools[].args menentukan cara AI Gateway mengubah parameter permintaan MCP menjadi komponen permintaan HTTP. Setiap entri menentukan tipe parameter, posisi (path, header, atau body), dan apakah parameter tersebut wajib.

Lokasi nilai parameter untuk transformasi gateway AI

AI Gateway mengekstraksi parameter dari body permintaan MCP sebagaimana ditentukan oleh protokol MCP. Mengekstraksi parameter dari lokasi lain seperti header permintaan saat ini tidak didukung.