API Gateway:HTTP to MCP configuration field reference

Server configuration

Allowed tools configuration

HTTP to MCP tool configuration

Defining authentication schemes (server.securitySchemes)

You can define a set of reusable authentication schemes at the server level. Tools can reference these schemes to configure how the MCP Server authenticates 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 you define server.securitySchemes, you can reference these schemes in each tool's requestTemplate.security field using the id. This specifies the authentication method that the MCP Server uses when it calls 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

The passthrough authentication feature allows credentials that are provided when an MCP client, such as an AI assistant, calls the MCP Server to be passed directly to the MCP Server. These credentials are then used to authenticate subsequent 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>.

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

When you use position to specify a parameter's location, the parameter is processed accordingly. It is not affected by batch parameter handling options, such as argsToJsonBody, argsToUrlParam, and argsToFormBody. These batch options affect only parameters that do not have 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 functions from Sprig. It provides more than 70 template functions for string manipulation, mathematical operations, date formatting, and more, offering capabilities equivalent to Helm's 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

For a complete reference of all available functions, see the Helm function documentation. GJSON Template includes the same function set.

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

For a complete GJSON path syntax reference, see the GJSON documentation.

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

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

This configuration uses the built-in `quark-search` MCP server in Higress. In this case, you only need to specify the server name and necessary configuration, such as an API key. You do not need to configure the `tools` field because the tools are predefined in the server.

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

The prependBody and appendBody fields are useful when you want to keep the original API response but add extra context. This is especially valuable when you transform an OpenAPI or Swagger specification into an MCP tool, because you can preserve the original JSON response while you provide explanations of the fields 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

The HTTP API to be transformed is: [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 and assembles an HTTP request based on the received MCP request parameters. It describes the properties of each parameter sent to the backend service, including the parameter type, position (such as path, header, or body), and whether it is required.

Parameter value location for AI gateway transformation

When processing an MCP request, the AI gateway extracts parameters from the request body at the location specified by the MCP protocol. The AI gateway does not currently support extracting parameters from other locations, such as request headers or other parts of the request body.