API Gateway：HTTP to MCP 配置欄位參考

伺服器配置

允許的工具配置

HTTP to MCP 工具配置

定義認證方案 (server.securitySchemes)

您可以在伺服器層級定義一組可重用的認證方案。這些方案可被各個工具引用，用於配置 MCP Server 向後端 HTTP API 發起請求時的認證方式。

配置欄位 (server.securitySchemes[])：

樣本 (server.securitySchemes)：

server:
  name: my-api-server
  securitySchemes:
    - id: MyBasicAuth
      type: http
      scheme: basic
      defaultCredential: "admin:secretpassword" # 預設的使用者名稱和密碼
    - id: MyBearerToken
      type: http
      scheme: bearer
      defaultCredential: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # 預設的Bearer Token
    - id: MyApiKeyInHeader
      type: apiKey
      in: header
      name: X-Custom-API-Key # API Key 在名為 X-Custom-API-Key 的 Header 中
      defaultCredential: "abcdef123456" # 預設的 API Key
    - id: MyApiKeyInQuery
      type: apiKey
      in: query
      name: "api_token" # API Key 在名為 api_token 的查詢參數中
      defaultCredential: "uvwxyz789012"

在工具中應用認證方案

定義了 server.securitySchemes 後，您可以在每個工具的 requestTemplate.security 中通過 id 引用這些方案，以指定 MCP Server 調用後端 HTTP API 時使用的認證方式。

• tools[].requestTemplate.security.id: 引用 server.securitySchemes 中定義的認證方案的 id。

• tools[].requestTemplate.security.credential: 可選。如果提供，它將覆蓋所引用方案中的 defaultCredential。這允許您為特定工具使用不同的憑證，即使它們共用相同的認證機制。

樣本：

tools:
  - name: get-user-details
    # ... 其他工具配置 ...
    requestTemplate:
      url: "https://api.example.com/users/{{.args.userId}}"
      method: GET
      security:
        id: MyBearerToken # 使用上面定義的 MyBearerToken 方案
        # credential: "override_token_for_this_tool" # 可選：為此工具覆蓋預設Token
  # ...
  - name: update-inventory
    # ... 其他工具配置 ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # 使用 MyApiKeyInHeader 方案
        # 此工具將使用 MyApiKeyInHeader 中定義的 defaultCredential

透明認證 (Passthrough Authentication)

透明認證功能允許在 MCP Client（例如 AI 助手）調用 MCP Server 時，將提供的憑證直接傳遞給 MCP Server，以用於後續調用後端 HTTP API 的認證過程。

配置方式：

1. 確保相關認證方案已在 server.securitySchemes 中定義。這包括用戶端用於串連到 MCP Server 的方案，以及 MCP Server 用於串連到後端 HTTP API 的方案。

2. 組態工具層級認證 (tools[].security): 在需要透傳憑證的工具中，配置 security 欄位：

   • id：引用 server.securitySchemes 中定義的、用於 MCP Client 與 MCP Server 之間的認證方案。外掛程式將根據此方案從用戶端請求中提取憑證，並清理原始請求中的該憑證。

   • passthrough: true：啟用透明認證。

3. 配置請求模板認證 (tools[].requestTemplate.security): 在工具的 requestTemplate 中，配置 security 欄位：

   • id: 引用 server.securitySchemes 中定義的、用於 MCP Server 與後端 HTTP API 之間的認證方案。

   • 當 tools[].security.passthrough 為 true 時，從用戶端提取的憑證將根據此 requestTemplate.security 方案應用於對後端 HTTP API 的調用。

樣本：

假設 MCP Client 使用 Bearer Token 調用 MCP Server，而 MCP Server 需要使用 API Key 調用後端的 HTTP API。

server:
  name: product-api-server
  securitySchemes:
    - id: ClientSideBearer # 用戶端使用Bearer Token
      type: http
      scheme: bearer
    - id: BackendApiKey    # 後端API使用X-API-Key
      type: apiKey
      in: header
      name: X-API-Key
      # defaultCredential: "optional_default_backend_key"

tools:
  - name: get-product-securely
    description: "擷取產品資訊（安全透傳）"
    security: # 用戶端 -> MCP Server 認證配置
      id: ClientSideBearer # MCP Server期望用戶端使用此方案，並會嘗試提取此類型的憑證
      passthrough: true   # 允許憑證透傳
    args:
      - name: product_id
        description: "產品ID"
        type: string
        required: true
    requestTemplate:
      security: # MCP Server -> 後端 HTTP API 認證配置
        id: BackendApiKey # 後端API需要此方案。透傳的憑證將按此方案應用。
      url: "https://api.example.com/products/{{.args.product_id}}"
      method: GET

工作流程：

1. MCP Client 發起請求到 MCP Server 的 get-product-securely 工具，並在 Authorization 頭中攜帶 Bearer <client_token>。

2. MCP Server 根據 tools[].security (id: ClientSideBearer) 識別出用戶端使用的是 Bearer Token。它會從請求中提取 <client_token> 並移除原始的 Authorization 頭。

3. 因為 passthrough: true，提取出的 <client_token> 被標記為透傳憑證。

4. MCP Server 準備調用後端 HTTP API。它查看 requestTemplate.security (id: BackendApiKey)。

5. 由於啟用了透傳，MCP Server 將之前提取的 <client_token> 作為憑證值，按照 BackendApiKey 方案（即作為名為 X-API-Key 的 HTTP Header）添加到對 https://api.example.com/products/... 的請求中。

6. 後端 HTTP API 收到請求，其中 X-API-Key Header 的值為 <client_token>。

支援的位置類型

• query: 參數將作為查詢參數添加到 URL 中。

• path: 參數將替換 URL 中的路徑預留位置，例如 /pet/{petId} 中的 {petId}。

• header: 參數將作為 HTTP 頭添加到請求中。

• cookie: 參數將作為 Cookie 添加到請求中。

• body: 參數將添加到請求體中（根據內容類型自動格式化為 JSON 或表單）。

使用樣本

args:
  - name: petId
    description: "寵物ID"
    type: string
    required: true
    position: path
  - name: token
    description: "認證令牌"
    type: string
    required: true
    position: header
  - name: sessionId
    description: "會話ID"
    type: string
    position: cookie
  - name: limit
    description: "返回結果數量"
    type: integer
    default: 10
    position: query
  - name: tags
    description: "標籤列表"
    type: array
    position: body

在上面的樣本中：

• petId 將替換 URL 中的 {petId} 預留位置。

• token 將作為 HTTP 頭添加到請求中。

• sessionId 將作為 Cookie 添加到請求中。

• limit 將作為查詢參數添加到 URL 中。

• tags 將添加到請求體中。

與批量參數處理選項的關係

當使用 position 指定參數位置時，這些參數將按照指定的位置處理，而不會受到批量參數處理選項（argsToJsonBody、argsToUrlParam、argsToFormBody）的影響。只有未指定 position 的參數才會受到這些批量選項的影響。

例如，如果您同時使用了 position 和 argsToJsonBody：

• 指定了 position: query 的參數會添加到 URL 查詢字串中。

• 指定了 position: header 的參數會添加到 HTTP 頭中。

• 指定了 position: path 的參數會替換 URL 中的預留位置。

• 指定了 position: cookie 的參數會添加到 Cookie 中。

• 指定了 position: body 的參數會添加到 JSON 請求體中。

• 未指定 position 的參數會通過 argsToJsonBody 添加到 JSON 請求體中。

此外，如果在 requestTemplate 中明確指定了 body，則所有 position: body 的參數都將被忽略，以避免衝突。

請求模板

用於構造 HTTP 要求 URL、頭部和本文：

• 訪問配置值：.config.欄位名。

• 訪問工具參數：.args.參數名。

響應模板

用於將 HTTP 響應轉換為適合 AI 消費的格式：

• 使用 GJSON 路徑文法訪問 JSON 響應欄位。

• 使用模板函數如 add、upper、lower 等。

• 使用控制結構如 if、range 等。

GJSON Template 包含了所有Sprig的函數，提供了 70+ 種用於字串操作、數學運算、日期格式化等的模板函數，功能等同於 Helm 的模板能力。

常用的 Sprig 函數包括：

• 字串操作：trim、upper、lower、replace、plural、nospace

• 數學運算：add、sub、mul、div、max、min

• 日期格式化：now、date、dateInZone、dateModify

• 列表操作：list、first、last、uniq、sortAlpha

• 字典操作：dict、get、set、hasKey、pluck

• 流程式控制制：ternary、default、empty、coalesce

• 類型轉換：toString、toJson、toPrettyJson、toRawJson

• 編碼/解碼：b64enc、b64dec、urlquery、urlqueryescape

• UUID 產生：uuidv4

有關所有可用函數的完整參考，請參閱 Helm 函數文檔，因為 GJSON Template 包含了相同的函數集。

GJSON 路徑文法

GJSON 提供了強大的 JSON 查詢能力：

• 點標記法：address.city

• 數組索引：users.0.name

• 數組迭代：users.#.name

• 數組過濾：users.#(age>=30)#.name

• 修飾符：users.@reverse.#.name

• 多重路徑：{name:users.0.name,count:users.#}

• 逸出字元：path.with\.dot

對於更複雜的查詢，可以使用 gjson 函數：

<!-- 使用 gjson 函數進行複雜查詢 -->
活躍使用者: {{gjson "users.#(active==true)#.name"}}

<!-- 帶有多個條件的數組過濾 -->
30歲以上的活躍開發人員: {{gjson "users.#(active==true && age>30)#.name"}}

<!-- 使用修飾符 -->
使用者名稱（倒序）: {{gjson "users.@reverse.#.name"}}

<!-- 迭代過濾結果 -->
管理員:
{{range $user := gjson "users.#(roles.#(==admin)>0)#"}}
 - {{$user.name}} ({{$user.age}})
{{end}}

完整的 GJSON 路徑文法參考可查看 GJSON 文檔。

使用內建 MCP 伺服器樣本：配置 quark-search

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

此配置使用了 Higress 內建的 quark-search MCP 伺服器。在這種情況下，只需要指定伺服器名稱和必要的配置（如 API 金鑰），無需配置 tools 欄位，因為工具已經在伺服器中預定義好了。

基礎配置樣本：轉換高德地圖 API

server:
  name: HTTP-amap-server
  config:
    apiKey: your-api-key-here
tools:
  - name: maps-geo
    description: "將詳細的結構化地址轉換為經緯度座標。支援對地標性名勝景區、建築物名稱解析為經緯度座標"
    args:
      - name: address
        description: "待解析的結構化地址資訊"
        type: string
        required: true
      - name: city
        description: "指定查詢的城市"
        type: string
        required: false
      - name: output
        description: "輸出格式"
        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: |
        # 地理編碼資訊
        {{- range $index, $geo := .geocodes }}
        ## 地點 {{add $index 1}}

        - **國家**: {{ $geo.country }}
        - **省份**: {{ $geo.province }}
        - **城市**: {{ $geo.city }}
        - **城市代碼**: {{ $geo.citycode }}
        - **區/縣**: {{ $geo.district }}
        - **街道**: {{ $geo.street }}
        - **門牌號**: {{ $geo.number }}
        - **行政編碼**: {{ $geo.adcode }}
        - **座標**: {{ $geo.location }}
        - **層級**: {{ $geo.level }}
        {{- end }}

此配置將高德地圖的地理編碼 API 轉換為 AI 可調用的工具。當 AI 調用此工具時：

1. 使用提供的地址和城市參數構建 API 請求。

2. 調用高德地圖 API。

3. 將 JSON 響應轉換為易於閱讀的 Markdown 格式。

4. 將格式化後的結果返回給 AI 助手。

進階配置樣本：帶有條件邏輯的複雜響應處理

server:
  name: weather-api-server
  config:
    apiKey: your-weather-api-key
tools:
  - name: get-weather
    description: "擷取指定城市的天氣預報資訊"
    args:
      - name: city
        description: "城市名稱"
        type: string
        required: true
      - name: days
        description: "天數(1-7)"
        type: integer
        required: false
        default: 3
      - name: include_hourly
        description: "是否包含每小時預報"
        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}} 天氣預報

        **當前溫度**: {{.current.temp_c}}°C
        **體感溫度**: {{.current.feelslike_c}}°C
        **天氣狀況**: {{.current.condition.text}}
        **濕度**: {{.current.humidity}}%
        **風速**: {{.current.wind_kph}} km/h

        ## 未來預報
        {{range $index, $day := .forecast.forecastday}}
        ### {{$day.date}} ({{dateFormat "Monday" $day.date_epoch | title}})

        {{if gt $day.day.maxtemp_c 30}}**高溫預警!**{{end}}
        {{if lt $day.day.mintemp_c 0}}**低溫預警!**{{end}}

        - **最高溫度**: {{$day.day.maxtemp_c}}°C
        - **最低溫度**: {{$day.day.mintemp_c}}°C
        - **降水機率**: {{$day.day.daily_chance_of_rain}}%
        - **天氣狀況**: {{$day.day.condition.text}}

        #### 分時預報
        {{range $hour := slice $day.hour 6 24 3}}
        - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
        {{end}}
        {{end}}
```

此樣本展示了：

• 使用條件陳述式（if）進行溫度警告。

• 使用日期格式化函數 (dateFormat)。

• 使用數組切片（slice）選擇特定時間的天氣。

• 嵌套迴圈遍曆多天和多時段的天氣資料。

使用 PrependBody 和 AppendBody 的樣本：OpenAPI 轉換

當您想保留原始 API 響應但添加額外的上下文資訊時，prependBody 和 appendBody 欄位非常有用。這在將 OpenAPI/Swagger 規範轉換為 MCP 工具時特別有價值，因為您可以保留原始 JSON 響應，同時為 AI 助手提供欄位含義的說明。

server:
  name: product-api-server
  config:
    apiKey: your-api-key-here
tools:
  - name: get-product
    description: "擷取產品詳細資料"
    args:
      - name: product_id
        description: "產品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: |
        # 產品資訊

        以下是產品的詳細資料，以JSON格式返回。欄位說明：

        - **id**: 產品唯一識別碼
        - **name**: 產品名稱
        - **description**: 產品描述
        - **price**: 產品價格（美元）
        - **category**: 產品類別
        - **inventory**: 庫存資訊
        - **quantity**: 當前庫存數量
        - **warehouse**: 倉庫位置
        - **ratings**: 使用者評分列表
        - **score**: 評分（1-5）
        - **comment**: 評論內容
      appendBody: |

        您可以使用這些資訊來瞭解產品的詳細資料、價格、庫存狀態和使用者評價。

此樣本展示了：

• 使用 prependBody 在原始 JSON 響應前添加欄位說明。

• 使用 appendBody 在響應末尾添加使用建議。

• 保留原始 JSON 響應，使 AI 助手可以直接存取所有資料。

我的 API 資訊

我想轉換的 HTTP API 是：[在此描述您的 API，包括端點、參數和響應格式，或者粘貼 Swagger/OpenAPI 規範]。

請根據以上資訊產生一個完整的配置，包括：
1. 具有描述性名稱和適當的伺服器配置。
2. 定義所有必要的參數，並提供清晰的描述和適當的類型、必填/預設值。
3. 選擇合適的參數傳遞方式（argsToUrlParam、argsToJsonBody、argsToFormBody 或自訂 body）。
4. 建立將 API 響應轉換為適合 AI 消費的可讀格式的 responseTemplate。

YAML中tools[].args的填寫規範

tools[].args參數用於定義AI網關在接收MCP請求參數後，將其轉換並組裝為HTTP請求的規範，具體描述了發送至後端服務的HTTP請求中各參數的屬性，包括參數類型、參數位置（如路徑、要求標頭、請求體）以及是否為必填參數。

AI網關在轉換時參數取值位置

AI網關接收到MCP請求後，將根據MCP協議規範從請求體對應位置提取參數，暫不支援從其餘位置（如要求標頭，請求體中其他位置）提取參數。