API Gateway:HTTP to MCP configuration field reference

Server configuration

Allowed tools configuration

HTTP to MCP tool configuration

Defining authentication schemes (server.securitySchemes)

Define reusable authentication schemes at the server level. Tools reference these schemes to authenticate with backend HTTP APIs.

Configuration fields (server.securitySchemes[]):

Example (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"

Applying authentication schemes in tools

After defining server.securitySchemes, reference schemes in each tool's requestTemplate.security field by id to specify how the MCP Server authenticates with the backend HTTP API.

• tools[].requestTemplate.security.id: References the id of an authentication scheme defined in server.securitySchemes.

• tools[].requestTemplate.security.credential: Optional. If provided, this field overrides the defaultCredential in the referenced scheme. This lets you use different credentials for specific tools, even if they share the same authentication mechanism.

Example:

tools:
  - name: get-user-details
    # ... other tool configurations ...
    requestTemplate:
      url: "https://api.example.com/users/{{.args.userId}}"
      method: GET
      security:
        id: MyBearerToken # Use the MyBearerToken scheme defined above
        # credential: "override_token_for_this_tool" # Optional: Override the default token for this tool
  # ...
  - name: update-inventory
    # ... other tool configurations ...
    requestTemplate:
      url: "https://api.example.com/inventory/{{.args.itemId}}"
      method: POST
      security:
        id: MyApiKeyInHeader # Use the MyApiKeyInHeader scheme
        # This tool will use the defaultCredential defined in MyApiKeyInHeader

Passthrough authentication

Passthrough authentication allows credentials provided by an MCP Client to be forwarded through the MCP Server to authenticate calls to the backend HTTP API.

Configuration method:

1. Ensure that the relevant authentication schemes are defined in server.securitySchemes. This includes the scheme that the client uses to connect to the MCP Server and the scheme that the MCP Server uses to connect to the backend HTTP API.

2. Configure tool-level authentication (tools[].security): For a tool that requires credential passthrough, configure the security field:

   • id: References the authentication scheme defined in server.securitySchemes that is used for authentication between the MCP Client and the MCP Server. The plugin extracts the credential from the client request based on this scheme and removes that credential from the original request.

   • passthrough: true: Enables passthrough authentication.

3. Configure request template authentication (tools[].requestTemplate.security): Configure the security field in the tool's requestTemplate:

   • id: References the authentication scheme defined in server.securitySchemes that is used for authentication between the MCP Server and the backend HTTP API.

   • When tools[].security.passthrough is set to true, the credential that is extracted from the client is applied to the call to the backend HTTP API according to this requestTemplate.security scheme.

Example:

Assume that the MCP client uses a Bearer Token to call the MCP Server, and the MCP Server needs to use an API key to call the backend HTTP API.

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

Workflow

1. The MCP client sends a request to the get-product-securely tool on the MCP Server. The request carries Bearer <client_token> in the Authorization header.

2. The MCP Server identifies that the client is using a Bearer Token based on tools[].security (id: ClientSideBearer). It extracts <client_token> from the request and removes the original Authorization header.

3. Because passthrough: true is set, the extracted <client_token> is marked as a passthrough credential.

4. The MCP Server prepares to call the backend HTTP API. It checks requestTemplate.security (id: BackendApiKey).

5. Because passthrough is enabled, the MCP Server uses the previously extracted <client_token> as the credential value. It adds this value to the request to https://api.example.com/products/... as an HTTP header named X-API-Key, according to the BackendApiKey scheme.

6. The backend HTTP API receives the request with the X-API-Key header set to <client_token>.

Troubleshooting: Passthrough credentials not taking effect

If the credential passed through from the client is not applied to the backend HTTP API call, and the MCP Server falls back to using the defaultCredential defined in server.securitySchemes instead, check the following configuration items:

• Confirm that passthrough is enabled at the tool level: Check that tools[].security.passthrough is set to true for the specific tool. Passthrough only takes effect for the tool where it is explicitly configured; it is not a global setting.

• Confirm that the referenced authentication scheme matches the credential type sent by the client or SDK: Check that the scheme referenced by tools[].security.id (for example, ClientSideBearer) matches the actual credential type that the client or SDK sends. If the scheme expects a Bearer Token but the client sends a different credential type, the MCP Server cannot correctly extract the passthrough credential.

• Confirm that defaultCredential is a valid, usable credential: Check the defaultCredential value configured under the corresponding scheme in server.securitySchemes. It must be a valid credential accepted by the backend HTTP API (for example, a well-formed JWT for a Bearer Token scheme), not a template placeholder. When passthrough does not take effect, the MCP Server falls back to using defaultCredential for the backend call. If defaultCredential is invalid, authentication against the backend HTTP API fails.

Supported position types

• query: The parameter is passed as a query parameter in the URL.

• path: The parameter replaces a path placeholder in the URL, such as {petId} in /pet/{petId}.

• header: The parameter is passed in an HTTP header.

• cookie: The parameter is passed as a cookie.

• body: The parameter is passed in the request body. It is automatically formatted as JSON or a form based on the content type.

Example

args:
  - name: petId
    description: "Pet ID"
    type: string
    required: true
    position: path
  - name: token
    description: "Authentication token"
    type: string
    required: true
    position: header
  - name: sessionId
    description: "Session ID"
    type: string
    position: cookie
  - name: limit
    description: "Number of results to return"
    type: integer
    default: 10
    position: query
  - name: tags
    description: "List of tags"
    type: array
    position: body

In the example above:

• petId replaces the {petId} placeholder in the URL.

• token is added to the request as an HTTP header.

• sessionId is added to the request as a cookie.

• limit is added to the URL as a query parameter.

• tags is added to the request body.

Relationship with batch parameter handling options

Parameters with a specified position are not affected by batch options (argsToJsonBody, argsToUrlParam, argsToFormBody). Batch options only apply to parameters without a specified position.

For example, if you use both position and argsToJsonBody:

• A parameter with position: query is added to the URL query string.

• A parameter with position: header is added to the HTTP headers.

• A parameter with position: path replaces a placeholder in the URL.

• A parameter with position: cookie is added as a cookie.

• A parameter with position: body is added to the JSON request body.

• Parameters without a specified position are added to the JSON request body by argsToJsonBody.

In addition, if you explicitly specify a body in the requestTemplate, all parameters with position: body are ignored to avoid conflicts.

Request template

You can use the request template to construct the HTTP request URL, headers, and body:

• To access configuration values, use .config.fieldName.

• To access tool parameters, use .args.parameterName.

Response template

You can use the response template to transform the HTTP response into a format that is suitable for AI consumption:

• To access JSON response fields, use GJSON path syntax.

• You can use template functions such as add, upper, and lower.

• You can use control structures such as if and range.

GJSON Template includes all Sprig functions (70+ functions equivalent to Helm templates):

Common Sprig functions include the following:

• String manipulation: trim, upper, lower, replace, plural, nospace

• Mathematical operations: add, sub, mul, div, max, min

• Date formatting: now, date, dateInZone, dateModify

• List operations: list, first, last, uniq, sortAlpha

• Dictionary operations: dict, get, set, hasKey, pluck

• Flow control: ternary, default, empty, coalesce

• Type conversion: toString, toJson, toPrettyJson, toRawJson

• Encoding/Decoding: b64enc, b64dec, urlquery, urlqueryescape

• UUID generation: uuidv4

GJSON Template includes the same function set as Helm template functions.

GJSON path syntax

GJSON provides powerful JSON query capabilities:

• Dot notation: address.city

• Array index: users.0.name

• Array iteration: users.#.name

• Array filtering: users.#(age>=30)#.name

• Modifiers: users.@reverse.#.name

• Multiple paths: {name:users.0.name,count:users.#}

• Escaped characters: path.with\.dot

For more complex queries, you can use the gjson function:

<!-- 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}}

Full path syntax is documented in the GJSON documentation.

Example of using a built-in MCP server: Configuring quark-search

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

Uses the built-in `quark-search` MCP server in Higress. Only the server name and necessary configuration such as an API key are needed — tools are predefined.

Basic example: Transforming the AMAP API

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 }}

This configuration transforms the AMAP geocoding API into a tool that an AI can call. When the AI calls this tool:

1. Builds an API request using the provided address and city parameters.

2. Calls the AMAP API.

3. Transforms the JSON response into a readable Markdown format.

4. Returns the formatted result to the AI assistant.

Advanced example: Complex response handling with conditional logic

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

This example demonstrates:

• Use a conditional statement (if) to issue temperature warnings.

• Use the date formatting function (dateFormat) to format dates.

• Use an array slice (slice) to select weather data for a specific time.

• Use nested loops to traverse weather data across multiple days and time periods.

Example of using prependBody and appendBody: OpenAPI transformation

Use prependBody and appendBody to add context around the original API response. This is useful for OpenAPI transformations where you preserve the raw JSON but add field explanations for the AI assistant.

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.

This example shows how to:

• Use prependBody to add field descriptions before the original JSON response.

• Use appendBody to add usage suggestions at the end of the response.

• Preserve the original JSON response so that the AI assistant can directly access all the data.

My API information

[Describe your API here, including its endpoints, parameters, and response format, or paste the Swagger/OpenAPI specification.]

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.

Specification for filling out tools[].args in YAML

The tools[].args parameter defines how the AI Gateway transforms MCP request parameters into HTTP request components. Each entry specifies the parameter type, position (path, header, or body), and whether it is required.

Parameter value location for AI gateway transformation

The AI Gateway extracts parameters from the MCP request body as specified by the MCP protocol. Extracting parameters from other locations such as request headers is not currently supported.