API Gateway:HTTP to MCP configuration field reference

サーバー構成

許可されるツールの構成

HTTP to MCP ツール構成

認証スキームの定義 (server.securitySchemes)

サーバーレベルで再利用可能な認証スキームのセットを定義できます。ツールはこれらのスキームを参照して、MCP サーバーがバックエンド 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 トークン
    - id: MyApiKeyInHeader
      type: apiKey
      in: header
      name: X-Custom-API-Key # API キーは X-Custom-API-Key という名前のヘッダーにあります
      defaultCredential: "abcdef123456" # デフォルトの API キー
    - id: MyApiKeyInQuery
      type: apiKey
      in: query
      name: "api_token" # API キーは api_token という名前のクエリパラメーターにあります
      defaultCredential: "uvwxyz789012"

ツールでの認証スキームの適用

server.securitySchemes を定義した後、各ツールの requestTemplate.security フィールドで id を使用してこれらのスキームを参照できます。これにより、MCP サーバーがバックエンド 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" # オプション: このツールのデフォルトトークンをオーバーライド
  # ...
  - name: update-inventory
    # ... その他のツール構成 ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # MyApiKeyInHeader スキームを使用
        # このツールは MyApiKeyInHeader で定義された defaultCredential を使用します

パススルー認証

パススルー認証機能により、AI アシスタントなどの MCP クライアントが MCP サーバーを呼び出すときに提供される認証情報を、MCP サーバーに直接渡すことができます。これらの認証情報は、バックエンド HTTP API への後続の呼び出しを認証するために使用されます。

設定方法：

1. 関連する認証スキームが server.securitySchemes で定義されていることを確認します。これには、クライアントが MCP サーバーに接続するために使用するスキームと、MCP サーバーがバックエンド HTTP API に接続するために使用するスキームが含まれます。

2. ツールレベルの認証を設定します (tools[].security)：認証情報のパススルーが必要なツールの場合、security フィールドを設定します：

   • id：MCP クライアントと MCP サーバー間の認証に使用される server.securitySchemes で定義された認証スキームを参照します。プラグインは、このスキームに基づいてクライアントリクエストから認証情報を抽出し、元のリクエストからその認証情報を削除します。

   • passthrough: true：パススルー認証を有効にします。

3. リクエストテンプレートの認証を設定します (tools[].requestTemplate.security)：ツールの requestTemplate で security フィールドを設定します：

   • id：MCP サーバーとバックエンド HTTP API 間の認証に使用される server.securitySchemes で定義された認証スキームを参照します。

   • tools[].security.passthrough が true に設定されている場合、クライアントから抽出された認証情報は、この requestTemplate.security スキームに従ってバックエンド HTTP API への呼び出しに適用されます。

例:

MCP クライアントが Bearer トークンを使用して MCP サーバーを呼び出し、MCP サーバーが API キーを使用してバックエンド HTTP API を呼び出す必要があると仮定します。

server:
  name: product-api-server
  securitySchemes:
    - id: ClientSideBearer # クライアントは Bearer トークンを使用
      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 サーバー認証設定
      id: ClientSideBearer # MCP サーバーはクライアントがこのスキームを使用することを期待し、このタイプの認証情報を抽出しようとします
      passthrough: true   # 認証情報のパススルーを許可
    args:
      - name: product_id
        description: "プロダクト ID"
        type: string
        required: true
    requestTemplate:
      security: # MCP サーバー -> バックエンド HTTP API 認証設定
        id: BackendApiKey # バックエンド API はこのスキームを必要とします。パススルー認証情報はこのスキームに従って適用されます。
      url: "https://api.example.com/products/{{.args.product_id}}"
      method: GET

ワークフロー

1. MCP クライアントは、MCP サーバー上の get-product-securely ツールにリクエストを送信します。リクエストは Authorization ヘッダーに Bearer <client_token> を含みます。

2. MCP サーバーは、tools[].security (id: ClientSideBearer) に基づいて、クライアントが Bearer トークンを使用していることを識別します。リクエストから <client_token> を抽出し、元の Authorization ヘッダーを削除します。

3. passthrough: true が設定されているため、抽出された <client_token> はパススルー認証情報としてマークされます。

4. MCP サーバーは、バックエンド HTTP API を呼び出す準備をします。requestTemplate.security (id: BackendApiKey) をチェックします。

5. パススルーが有効になっているため、MCP サーバーは以前に抽出した <client_token> を認証情報の値として使用します。BackendApiKey スキームに従って、この値を X-API-Key という名前の HTTP ヘッダーとして https://api.example.com/products/... へのリクエストに追加します。

6. バックエンド HTTP API は、X-API-Key ヘッダーが <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 はクッキーとしてリクエストに追加されます。

• 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.fieldName を使用します。

• ツールパラメーターにアクセスするには、.args.parameterName を使用します。

レスポンステンプレート

レスポンステンプレートを使用して、HTTP レスポンスを AI が消費するのに適したフォーマットに変換できます：

• JSON レスポンスフィールドにアクセスするには、GJSON パス構文を使用します。

• add、upper、lower などのテンプレート関数を使用できます。

• if や range などの制御構造を使用できます。

GJSON テンプレートには、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 テンプレートには同じ関数セットが含まれています。

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` フィールドを設定する必要はありません。

基本例：AMAP 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 }}
        - **Adcode**: {{ $geo.adcode }}
        - **場所**: {{ $geo.location }}
        - **レベル**: {{ $geo.level }}
        {{- end }}

この設定は、AMAP ジオコーディング API を AI が呼び出せるツールに変換します。AI がこのツールを呼び出すと：

1. 提供された住所と都市のパラメーターを使用して API リクエストを構築します。

2. AMAP 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 変換

prependBody と appendBody フィールドは、元の API レスポンスを保持しつつ、追加のコンテキストを加えたい場合に便利です。これは、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**: プロダクト価格 (USD)
        - **category**: プロダクトカテゴリ
        - **inventory**: 在庫情報
        - **quantity**: 現在の在庫数量
        - **warehouse**: 倉庫の場所
        - **ratings**: ユーザー評価のリスト
        - **score**: 評価 (1-5)
        - **comment**: コメント内容
      appendBody: |

        この情報を使用して、プロダクトの詳細、価格、在庫状況、ユーザーレビューを理解できます。

この例は、次の方法を示しています:

• prependBody を使用して、元の JSON 応答の前にフィールドの説明を追加します。

• appendBody を使用して、応答の最後に使用方法の提案を追加します。

• AI アシスタントがすべてのデータに直接アクセスできるように、元の JSON レスポンスを保持します。

My API 情報

変換する HTTP API は次のとおりです：[ここに API を記述してください。エンドポイント、パラメーター、レスポンス形式を含めるか、Swagger/OpenAPI 仕様を貼り付けてください]。

上記の情報に基づいて、以下を含む完全な設定を生成してください：
1. 説明的な名前と適切なサーバー設定。
2. 必要なすべてのパラメーターの定義、明確な説明と適切なタイプ、必須/デフォルト値。
3. 最も適切なパラメーター受け渡しメソッド (argsToUrlParam、argsToJsonBody、argsToFormBody、またはカスタムボディ)。
4. API レスポンスを AI が消費するのに適した読みやすい形式に変換する responseTemplate。