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协议规范从请求体对应位置提取参数，暂不支持从其余位置（如请求头，请求体中其他位置）提取参数。