API Gateway：Referensi bidang konfigurasi HTTP ke MCP

Konfigurasi server

Konfigurasi alat yang diizinkan

Konfigurasi alat HTTP ke MCP

Mendefinisikan skema autentikasi (server.securitySchemes)

Anda dapat mendefinisikan serangkaian skema autentikasi yang dapat digunakan kembali di tingkat server. Tool dapat mereferensikan skema ini untuk mengonfigurasi cara MCP Server melakukan autentikasi dengan HTTP API backend.

Bidang konfigurasi (server.securitySchemes[]):

Contoh (server.securitySchemes):

server:
  name: my-api-server
  securitySchemes:
    - id: MyBasicAuth
      type: http
      scheme: basic
      defaultCredential: "admin:secretpassword" # Default username and password
    - id: MyBearerToken
      type: http
      scheme: bearer
      defaultCredential: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # Default Bearer Token
    - id: MyApiKeyInHeader
      type: apiKey
      in: header
      name: X-Custom-API-Key # API key is in a header named X-Custom-API-Key
      defaultCredential: "abcdef123456" # Default API key
    - id: MyApiKeyInQuery
      type: apiKey
      in: query
      name: "api_token" # API key is in a query parameter named api_token
      defaultCredential: "uvwxyz789012"

Menerapkan skema autentikasi dalam tool

Setelah Anda mendefinisikan server.securitySchemes, Anda dapat mereferensikan skema ini di bidang requestTemplate.security setiap tool menggunakan id. Hal ini menentukan metode autentikasi yang digunakan MCP Server saat memanggil HTTP API backend.

• tools[].requestTemplate.security.id: Merujuk pada id skema autentikasi yang didefinisikan dalam server.securitySchemes.

• tools[].requestTemplate.security.credential: Opsional. Jika disediakan, bidang ini menimpa 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 alat 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 alat ini
  # ...
  - name: update-inventory
    # ... konfigurasi alat lainnya ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # Menggunakan skema MyApiKeyInHeader
        # Alat ini akan menggunakan defaultCredential yang didefinisikan dalam MyApiKeyInHeader

Autentikasi passthrough

Fitur autentikasi passthrough memungkinkan kredensial yang diberikan saat client MCP, seperti asisten AI, memanggil MCP Server untuk diteruskan langsung ke MCP Server. Kredensial ini kemudian digunakan untuk mengautentikasi panggilan berikutnya ke HTTP API backend.

Metode konfigurasi:

1. Pastikan bahwa 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 HTTP API backend.

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

   • id: Merujuk pada 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 bidang security di requestTemplate tool:

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

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

Contoh:

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

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

tools:
  - name: get-product-securely
    description: "Get product information (secure passthrough)"
    security: # Client -> MCP Server authentication configuration
      id: ClientSideBearer # The MCP Server expects the client to use this scheme and will try to extract this type of credential
      passthrough: true   # Allow credential passthrough
    args:
      - name: product_id
        description: "Product ID"
        type: string
        required: true
    requestTemplate:
      security: # MCP Server -> backend HTTP API authentication configuration
        id: BackendApiKey # The backend API requires this scheme. The passthrough credential will be applied according to this scheme.
      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 HTTP API backend. Server memeriksa requestTemplate.security (id: BackendApiKey).

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

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

Jenis posisi yang didukung

• query: Parameter dilewatkan sebagai parameter query di URL.

• path: Parameter menggantikan placeholder path di URL, seperti {petId} dalam /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 badan permintaan.

Hubungan dengan opsi penanganan parameter batch

Ketika Anda menggunakan position untuk menentukan lokasi parameter, parameter tersebut diproses sesuai. Parameter ini tidak terpengaruh oleh opsi penanganan parameter batch, seperti argsToJsonBody, argsToUrlParam, dan argsToFormBody. Opsi batch ini hanya memengaruhi parameter yang tidak memiliki position yang ditentukan.

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

• Parameter dengan position: query ditambahkan ke string query 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 badan 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 bidang respons JSON, gunakan sintaksis path GJSON.

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

• Anda dapat menggunakan struktur kendali seperti if dan range.

GJSON Template mencakup semua fungsi dari Sprig. Library ini menyediakan lebih dari 70 fungsi templat untuk manipulasi string, operasi matematika, pemformatan tanggal, dan lainnya, menawarkan kemampuan 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

• Pengkodean/Pendekodean: b64enc, b64dec, urlquery, urlqueryescape

• Generasi UUID: uuidv4

Untuk referensi lengkap semua fungsi yang tersedia, lihat dokumentasi fungsi Helm. GJSON Template mencakup set fungsi yang sama.

Sintaksis path GJSON

GJSON menyediakan kemampuan kueri JSON yang kuat:

• Notasi Titik: address.city

• Indeks array: users.0.name

• Iterasi Array: users.#.name

• Penyaringan 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:

<!-- Use the gjson function for complex queries -->
Active users: {{gjson "users.#(active==true)#.name"}}

<!-- Array filtering with multiple conditions -->
Active developers over 30: {{gjson "users.#(active==true && age>30)#.name"}}

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

<!-- Iterating over filtered results -->
Administrators:
{{range $user := gjson "users.#(roles.#(==admin)>0)#"}}
 - {{$user.name}} ({{$user.age}})
{{end}}

Untuk referensi sintaksis path GJSON lengkap, lihat dokumentasi GJSON.

Contoh penggunaan server MCP bawaan: Mengonfigurasi quark-search

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

Konfigurasi ini menggunakan server MCP bawaan quark-search di Higress. Dalam kasus ini, Anda hanya perlu menentukan nama server dan konfigurasi yang diperlukan, seperti API key. Anda tidak perlu mengonfigurasi bidang tools karena tool sudah ditentukan sebelumnya di server.

Contoh dasar: Mengubah API AMAP

server:
  name: HTTP-amap-server
  config:
    apiKey: your-api-key-here
tools:
  - name: maps-geo
    description: "Converts a detailed, structured address into latitude and longitude coordinates. Supports resolving landmarks, scenic spots, and building names to coordinates."
    args:
      - name: address
        description: "The structured address to be resolved."
        type: string
        required: true
      - name: city
        description: "The city to query."
        type: string
        required: false
      - name: output
        description: "Output format."
        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: |
        # Geocoding Information
        {{- range $index, $geo := .geocodes }}
        ## Location {{add $index 1}}

        - **Country**: {{ $geo.country }}
        - **Province**: {{ $geo.province }}
        - **City**: {{ $geo.city }}
        - **City Code**: {{ $geo.citycode }}
        - **District**: {{ $geo.district }}
        - **Street**: {{ $geo.street }}
        - **Street Number**: {{ $geo.number }}
        - **Adcode**: {{ $geo.adcode }}
        - **Location**: {{ $geo.location }}
        - **Level**: {{ $geo.level }}
        {{- end }}

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

1. Membangun permintaan API menggunakan parameter address dan city 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: "Gets the weather forecast for a specified city."
    args:
      - name: city
        description: "City name"
        type: string
        required: true
      - name: days
        description: "Number of days (1-7)"
        type: integer
        required: false
        default: 3
      - name: include_hourly
        description: "Specifies whether to include the hourly forecast."
        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: |
        # {{.location.name}}, {{.location.country}} Weather Forecast

        **Current Temperature**: {{.current.temp_c}}°C
        **Feels Like**: {{.current.feelslike_c}}°C
        **Condition**: {{.current.condition.text}}
        **Humidity**: {{.current.humidity}}%
        **Wind Speed**: {{.current.wind_kph}} km/h

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

        {{if gt $day.day.maxtemp_c 30}}**High temperature warning!**{{end}}
        {{if lt $day.day.mintemp_c 0}}**Low temperature warning!**{{end}}

        - **Max Temperature**: {{$day.day.maxtemp_c}}°C
        - **Min Temperature**: {{$day.day.mintemp_c}}°C
        - **Chance of Rain**: {{$day.day.daily_chance_of_rain}}%
        - **Condition**: {{$day.day.condition.text}}

        #### Hourly Forecast
        {{range $hour := slice $day.hour 6 24 3}}
        - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
        {{end}}
        {{end}}
```<p>This example shows how to:</p><ul><li><p>Use conditional statements (<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 potongan array (slice) untuk memilih data cuaca pada waktu tertentu.

• Menggunakan loop bersarang untuk menelusuri data cuaca lintas beberapa hari dan periode waktu.

Contoh penggunaan prependBody dan appendBody: Transformasi OpenAPI

Bidang prependBody dan appendBody berguna ketika Anda ingin mempertahankan respons API asli tetapi menambahkan konteks tambahan. Hal ini sangat berharga saat Anda mengubah spesifikasi OpenAPI atau Swagger menjadi tool MCP, karena Anda dapat mempertahankan respons JSON asli sambil memberikan penjelasan bidang untuk asisten AI.

server:
  name: product-api-server
  config:
    apiKey: your-api-key-here
tools:
  - name: get-product
    description: "Get product details"
    args:
      - name: product_id
        description: "Product ID"
        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: |
        # Product Information

        The following are the product details, returned in JSON format. Field descriptions:

        - **id**: The unique product identifier
        - **name**: The product name
        - **description**: The product description
        - **price**: The product price (USD)
        - **category**: The product category
        - **inventory**: Inventory information
        - **quantity**: The current stock quantity
        - **warehouse**: The warehouse location
        - **ratings**: A list of user ratings
        - **score**: The rating (1-5)
        - **comment**: The comment content
      appendBody: |

        You can use this information to understand the product's details, price, inventory status, and user reviews.

Contoh ini menunjukkan cara:

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

• Menggunakan appendBody untuk menambahkan saran penggunaan di akhir respons.

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

Informasi API saya

HTTP API yang akan diubah adalah: [Jelaskan API Anda di sini, termasuk endpoint, parameter, dan format responsnya, atau tempelkan spesifikasi Swagger/OpenAPI].

Based on the information above, generate a complete configuration that includes:
1. A descriptive name and appropriate server configuration.
2. Definitions for all necessary parameters, with clear descriptions and appropriate types, required/default values.
3. The most suitable parameter passing method (argsToUrlParam, argsToJsonBody, argsToFormBody, or a custom body).
4. A responseTemplate that transforms the API response into a readable format suitable for AI consumption.