API Gateway:HTTP to MCP 設定フィールドリファレンス

サーバー設定

許可されたツールの設定

HTTP to MCP ツール設定

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

サーバーレベルで再利用可能な認証スキームを定義します。ツールはこれらのスキームを参照して、バックエンド 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..." # デフォルトのベアラートークン
    - 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 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" # 任意: このツールのデフォルトトークンをオーバーライドします
  # ...
  - name: update-inventory
    # ... その他のツール設定 ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # MyApiKeyInHeader スキームを使用します
        # このツールは MyApiKeyInHeader で定義された defaultCredential を使用します

パススルー認証

パススルー認証により、MCP Client が提供する認証情報を 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 がベアラートークンを使用して MCP Server を呼び出し、MCP Server は API キーを使用してバックエンド HTTP API を呼び出す必要があるとします。

server:
  name: product-api-server
  securitySchemes:
    - id: ClientSideBearer # クライアントはベアラートークンを使用します
      type: http
      scheme: bearer
    - id: BackendApiKey    # バックエンド API は X-API-Key を使用します
      type: apiKey
      in: header
      name: X-API-Key
      # defaultCredential: "(任意) デフォルトのバックエンドキー"

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) に基づいて、クライアントがベアラートークンを使用していることを識別します。リクエストから <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 ヘッダーとして https://api.example.com/products/... へのリクエストに追加します。

6. バックエンド HTTP API は、X-API-Key ヘッダーが <client_token> に設定されたリクエストを受信します。

トラブルシューティング：パススルー認証情報が有効にならない

クライアントからパススルーされた認証情報がバックエンド HTTP API 呼び出しに適用されず、MCP Server が代わりに server.securitySchemes で定義された defaultCredential を使用するようにフォールバックする場合は、以下の設定項目を確認してください：

• ツールレベルでパススルーが有効になっていることを確認します： 特定のツールの tools[].security.passthrough が true に設定されていることを確認してください。パススルーは、明示的に設定されたツールでのみ有効になります。グローバル設定ではありません。

• 参照された認証スキームがクライアントまたは SDK が送信する認証情報タイプと一致することを確認します： tools[].security.id によって参照されるスキーム (例： ClientSideBearer) が、クライアントまたは SDK が実際に送信する認証情報タイプと一致することを確認してください。スキームがベアラートークンを期待しているのに、クライアントが異なる認証情報タイプを送信している場合、MCP Server はパススルー認証情報を正しく抽出できません。

• defaultCredential が有効で使用可能な認証情報であることを確認します： server.securitySchemes の対応するスキームで設定された defaultCredential の値を確認してください。これは、バックエンド HTTP API が受け入れる有効な認証情報 (例：ベアラートークンスキームの場合は適切に形成された JWT) である必要があり、テンプレートプレースホルダーであってはなりません。パススルーが有効にならない場合、MCP Server はバックエンド呼び出しに defaultCredential を使用するようにフォールバックします。defaultCredential が無効な場合、バックエンド HTTP API に対する認証は失敗します。

対応する位置タイプ

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

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

レスポンステンプレート

レスポンステンプレートを使用して、HTTP レスポンスを AI での利用に適した形式に変換できます。

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

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

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

GJSON Template には、すべての Sprig 関数 (Helm テンプレートに相当する 70 以上の関数) が含まれています：

一般的な 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

GJSON Template には、Helm テンプレート関数と同じ関数セットが含まれています。

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 ドキュメントに記載されています。

組み込み MCP Server の使用例：quark-search の構成

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

Higress の組み込み quark-search MCP Server を使用します。サーバー名と API キーなどの必要な構成のみで、ツールは事前定義済みです。

基本例：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://restapi.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}}
        - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
        {{end}}
        {{end}}

この例では、以下について説明します。

• 条件文 (if) を使用して気温警告を発行します。

• 日付フォーマット関数 (dateFormat) を使用して日付をフォーマットします。

• 配列スライス (slice) を使用して特定の時間の天気データを選択します。

• ネストされたループを使用して、複数の日と時間帯にわたる天気データを走査します。

prependBody と appendBody の使用例：OpenAPI 変換

prependBody と appendBody を使用して、元の API レスポンスの前後にコンテキストを追加します。これは、生の JSON を保持しながら AI アシスタント向けにフィールドの説明を追加する OpenAPI 変換に役立ちます。

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 を使用して、レスポンスの末尾に使用方法の提案を追加します。

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

私の API 情報

[ここに API の詳細 (エンドポイント、パラメーター、レスポンス形式) を記述するか、Swagger/OpenAPI 仕様を貼り付けてください。]

上記の情報に基づいて、以下を含む完全な設定を生成してください:
1. わかりやすい名前と適切なサーバー設定。
2. すべての必要なパラメーターの定義 (明確な説明、適切な型、必須/デフォルト値を含む)。
3. 最も適切なパラメーター受け渡し方法 (argsToUrlParam、argsToJsonBody、argsToFormBody、またはカスタム body)。
4. API レスポンスを AI での利用に適した読みやすい形式に変換するレスポンステンプレート。

YAML における tools[].args の記入仕様

tools[].args パラメーターは、AI ゲートウェイが MCP リクエストパラメーターを HTTP リクエストコンポーネントに変換する方法を定義します。各エントリで、パラメーターの型、位置 (パス、ヘッダー、またはボディ)、および必須かどうかを指定します。

AI ゲートウェイの変換におけるパラメーター値の位置

AI ゲートウェイは、MCP プロトコルで指定されているとおりに MCP リクエストボディからパラメーターを抽出します。リクエストヘッダーなど、他の位置からのパラメーター抽出は現在サポートされていません。