HTTP 转 MCP 配置说明

更新时间：2026-04-17

快速开始：自定义 YAML 结构示例

参考这个 YAML 结构示例模板，可以快速扩展你的配置。

本模板案例为：一个 HTTP Server，有单独查询 item 、查询 item 列表、创建 item 三个接口。现在将这个 HTTP Server 转为 MCP Server，并将原来的三个接口转为 MCP Tool。

其中，list_items API 有权限校验。

Plain Text

1server:
2  name: YOUR-MCP-SERVER-NAME
3  # 类型。必须有，而且值为rest
4  type: rest
5  # 如果API没有鉴权逻辑，securitySchemes这一坨都可以删除
6  # defaultCredential的值，就是校验值
7  # 如果你有服务器级别的默认认证配置需求，参考下文的 defaultUpstreamSecurity 和 defaultDownstreamSecurity 字段
8  securitySchemes:
9    - id: ApiKeyAuth
10      defaultCredential: '123456'
11      type: apiKey
12      in: header
13      name: X-API-Key
14    - id: BasicAuth
15      defaultCredential: admin:admin123
16      type: http
17      scheme: basic
18    - id: BearerAuth
19      defaultCredential: asdf
20      type: http
21      scheme: bearer
22  # 一些配置信息。可以被后面的字段引用，引用方式为{{.config.xxxx}}
23  config:
24    # 比如在这里可以声明domain，在后面可以拿去引用
25    domain: 'http://localhost:8080'
26    ContentType: 'application/json'
27# 工具配置
28tools:
29  - args: # 工具的参数配置
30      - description: 商品ID # 参数的描述
31        # 参数名
32        name: id
33        # 参数位置
34        position: path
35        required: true
36        type: integer
37    # 工具描述
38    description: 获取商品 - 根据ID获取商品
39    # 工具名
40    name: get_item
41    # API的请求模板
42    requestTemplate:
43      headers:
44        - key: Content-Type
45          value: '{{.config.ContentType}}'
46      method: GET
47      # 比如在这里就可以引用在config里面配置的
48      url: '{{.config.domain}}/api/items/{id}'
49    # API 响应模板
50    responseTemplate:
51      # 在响应体前面可以加一些文本内容，比如一些结构化的描述，能让 LLM 更好理解。如果你使用了prependBody，就不能使用body，因为互斥。
52      prependBody: |
53        以下是响应内容
54   - args:
55    # 工具描述
56    description: 获取items列表，需要鉴权
57    # 工具名
58    name: list_item
59    # 在这一层配置security，是在你调用 MCP 工具时需要做的鉴权。如果没有，则不用配置security字段。
60    security:
61      # 引用的id是上面securitySchemes的id，注意一定要匹配id
62      id: BasicAuth
63    # API的请求体
64    requestTemplate:
65      # 这一层配置的就是对RestFul API的鉴权了。如果没有，则不用配置security字段
66      security:
67        id: BearerAuth
68      method: GET
69      # 比如在这里就可以引用在config里面配置的。甚至你可以使用当前工具的参数去做引用，如: {{.args.参数名}}
70      url: '{{.config.domain}}/api/items'
71    # API 响应模板
72    responseTemplate:
73      # 注意，如果不配置body的值，默认使用 API 的响应体的值。如果配置了，则使用你配置的值。想要读取原本响应体的值，需要使用模板语法。
74      # 如果你使用了body，就不能使用prependBody或appendBody，因为互斥。
75      body: |
76        {{range $index, $item := .data}}
77          id: {{$item.id}}
78          name: {{$item.name}}
79          描述: {{$item.description}}
80          价格: {{$item.price}}
81        {{end}}
82  - args: # POST请求的实例
83      - description: 商品描述
84        name: description
85        # 注意到这个参数位置到body了
86        position: body
87        type: string
88      - description: 商品名称
89        name: name
90        position: body
91        required: true
92        type: string
93      - description: 商品价格
94        name: price
95        position: body
96        required: true
97        type: number
98    description: 创建商品 - 创建一个新的商品
99    name: create_item
100    requestTemplate:
101      headers:
102        - key: Content-Type
103          value: 'application/json'
104      method: POST
105      url: '{{.config.domain}}/api/items'
106    responseTemplate:
107      # 什么都不配就使用原生Restful API的响应体
108      body:

更多使用说明见下文。

HTTP 转 MCP 配置

名称	数据类型	填写要求	默认值	描述
`tools`	array of object	选填	[]	HTTP 转 MCP 工具配置列表
`tools[].name`	string	必填	-	工具名称
`tools[].description`	string	必填	-	工具功能描述
`tools[].args`	array of object	必填	[]	工具参数定义
`tools[].args[].name`	string	必填	-	参数名称
`tools[].args[].description`	string	必填	-	参数描述
`tools[].args[].type`	string	选填	string	参数类型（string, number, integer, boolean, array, object）
`tools[].args[].required`	boolean	选填	false	参数是否必需
`tools[].args[].default`	any	选填	-	参数默认值
`tools[].args[].enum`	array	选填	-	参数允许的值列表
`tools[].args[].items`	object	选填	-	数组项的模式（当type为array时）
`tools[].args[].properties`	object	选填	-	对象属性的模式（当type为object时）
`tools[].args[].position`	string	选填	-	参数在请求中的位置（query, path, header, cookie, body）
`tools[].requestTemplate`	object	必填	-	HTTP 请求模板
`tools[].requestTemplate.url`	string	必填	-	请求 URL 模板
`tools[].requestTemplate.method`	string	必填	-	HTTP 方法(GET/POST等)
`tools[].requestTemplate.headers`	array of object	选填	[]	请求头模板
`tools[].requestTemplate.headers[].key`	string	必填	-	请求头名称
`tools[].requestTemplate.headers[].value`	string	必填	-	请求头值模板
`tools[].requestTemplate.body`	string	选填	-	请求体模板（与argsToJsonBody、argsToUrlParam、argsToFormBody互斥）
`tools[].requestTemplate.argsToJsonBody`	boolean	选填	false	当为true时，参数将直接用作JSON请求体（与body、argsToUrlParam、argsToFormBody互斥）
`tools[].requestTemplate.argsToUrlParam`	boolean	选填	false	当为true时，参数将作为查询参数添加到URL中（与body、argsToJsonBody、argsToFormBody互斥）
`tools[].requestTemplate.argsToFormBody`	boolean	选填	false	当为true时，参数将以application/x-www-form-urlencoded格式编码在请求体中（与body、argsToJsonBody、argsToUrlParam互斥）
`tools[].responseTemplate`	object	必填	-	HTTP 响应转换模板
`tools[].responseTemplate.body`	string	选填	-	响应体转换模板（与prependBody和appendBody互斥）
`tools[].responseTemplate.prependBody`	string	选填	-	在响应体前插入的文本（与body互斥）
`tools[].responseTemplate.appendBody`	string	选填	-	在响应体后插入的文本（与body互斥）
`tools[].security`	object	选填	-	工具级别安全配置，用于定义 MCP Client 和 MCP Server 之间的认证方式，并支持凭证透传。
`tools[].security.id`	string	当 `tools[].security` 配置时必填	-	引用在 `server.securitySchemes` 中定义的认证方案 ID。
`tools[].security.passthrough`	boolean	选填	false	是否启用透明认证。如果为 `true`，则从 MCP Client 请求中提取的凭证将用于 `requestTemplate.security` 定义的认证方案。
`tools[].requestTemplate.security`	object	选填	-	HTTP 请求模板的安全配置，用于定义 MCP Server 和 REST API 之间的认证方式。
`tools[].requestTemplate.security.id`	string	当`tools[].requestTemplate.security` 配置时必填	-	引用在 `server.securitySchemes` 中定义的认证方案 ID。
`tools[].requestTemplate.security.credential`	string	选填	-	覆盖 `server.securitySchemes` 中定义的默认凭证。如果同时启用了 `tools[].security.passthrough`，则此字段将被忽略，优先使用透传的凭证。
`tools[].errorResponseTemplate`	string	选填	-	HTTP响应Status>=300 或 Status <200 时的错误响应转换模板

认证与安全

本服务支持灵活的认证配置，以确保与后端 REST API 通信的安全性。支持认证配置：

HTTP 转 MCP (rest 类型)：将客户端请求转换为 REST API 调用

它支持两层认证机制：

客户端到网关认证：验证调用 MCP Server 的客户端身份
网关到后端认证：MCP Server 调用后端服务时的认证方式

定义认证方案 (`server.securitySchemes`)

您可以在服务器级别定义一组可重用的认证方案。这些方案之后可以被各个工具引用，用于配置 MCP Server 向后端 REST API 发起请求时的认证方式。

配置字段 (server.securitySchemes[]):

名称	数据类型	填写要求	描述
`id`	string	必填	认证方案的唯一标识符，供工具配置引用。
`type`	string	必填	认证类型，支持 `http` (用于 Basic 和 Bearer认证) 和 `apiKey`。
`scheme`	string	选填	当 `type` 为 `http` 时指定具体的方案，如 `basic` 或 `bearer`。
`in`	string	选填	当 `type` 为 `apiKey` 时指定 API 密钥的位置，如 `header` 或 `query`。
`name`	string	选填	当 `type` 为 `apiKey` 时指定 Header 名称或查询参数名称。
`defaultCredential`	string	选填	此方案的默认凭证。例如，对于 Basic Auth，可以是 "user:password"；对于 Bearer Token，是 Token 本身；对于 API Key，是 Key 本身。

示例 (server.securitySchemes):

Plain Text

1server:
2  name: my-api-server
3  securitySchemes:
4  - id: MyBasicAuth
5    type: http
6    scheme: basic
7    defaultCredential: "admin:secretpassword" # 默认的用户名和密码
8  - id: MyBearerToken
9    type: http
10    scheme: bearer
11    defaultCredential: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # 默认的Bearer Token
12  - id: MyApiKeyInHeader
13    type: apiKey
14    in: header
15    name: X-Custom-API-Key # API Key 在名为 X-Custom-API-Key 的 Header 中
16    defaultCredential: "abcdef123456" # 默认的 API Key
17  - id: MyApiKeyInQuery
18    type: apiKey
19    in: query
20    name: "api_token" # API Key 在名为 api_token 的查询参数中
21    defaultCredential: "uvwxyz789012"

在工具中应用认证方案

定义了 server.securitySchemes 后，您可以在每个工具的 requestTemplate.security 中通过 id 引用这些方案，以指定 MCP Server 调用后端 REST API 时使用的认证方式。

tools[].requestTemplate.security.id: 引用 server.securitySchemes 中定义的认证方案的 id。
tools[].requestTemplate.security.credential: 可选。如果提供，它将覆盖所引用方案中的 defaultCredential。这允许您为特定工具使用不同的凭证，即使它们共享相同的认证机制。

示例:

Plain Text

1tools:
2- name: get-user-details
3  # ... 其他工具配置 ...
4  requestTemplate:
5    url: "https://api.example.com/users/{{.args.userId}}"
6    method: GET
7    security:
8      id: MyBearerToken # 使用上面定义的 MyBearerToken 方案
9      # credential: "override_token_for_this_tool" # 可选：为此工具覆盖默认Token
10# ...
11- name: update-inventory
12  # ... 其他工具配置 ...
13  requestTemplate:
14    url: "https://api.example.com/inventory/{{.args.itemId}}"
15    method: POST
16    security:
17      id: MyApiKeyInHeader # 使用 MyApiKeyInHeader 方案
18      # 此工具将使用 MyApiKeyInHeader 中定义的 defaultCredential

透明认证 (Passthrough Authentication)

透明认证功能允许将 MCP Client (例如 AI 助手) 调用 MCP Server 时提供的凭证，透传给 MCP Server 调用后端 REST API 时的认证过程。

配置方式:

确保相关认证方案已在 server.securitySchemes 中定义。这包括客户端用于连接到 MCP Server 的方案，以及 MCP Server 用于连接到后端 REST API 的方案。

配置工具级别认证 (tools[].security): 在需要透传凭证的工具中，配置 security 字段：

Plain Text

1id: xxxx # 引用 server.securitySchemes 中定义的、用于 **MCP Client 与 MCP Server 之间**的认证方案。插件将根据此方案从客户端请求中提取凭证，并清理原始请求中的该凭证。
2passthrough: true  # 启用透明认证。

配置请求模板认证 (tools[].requestTemplate.security): 在工具的 requestTemplate 中，配置 security 字段：

Plain Text

1id: 引用 server.securitySchemes 中定义的、用于 **MCP Server 与后端 REST API 之间**的认证方案。
2当 tools[].security.passthrough 为 true 时，从客户端提取的凭证将根据此 requestTemplate.security 方案应用于对后端 REST API 的调用。

示例:

假设 MCP Client 使用 Bearer Token 调用 MCP Server，而 MCP Server 需要使用 API Key 调用后端的 REST API。

Plain Text

1server:
2  name: product-api-server
3  securitySchemes:
4  - id: ClientSideBearer # 客户端使用Bearer Token
5    type: http
6    scheme: bearer
7  - id: BackendApiKey    # 后端API使用X-API-Key
8    type: apiKey
9    in: header
10    name: X-API-Key
11    # defaultCredential: "optional_default_backend_key"
12
13tools:
14- name: get-product-securely
15  description: "获取产品信息（安全透传）"
16  security: # 客户端 -> MCP Server 认证配置
17    id: ClientSideBearer # MCP Server期望客户端使用此方案，并会尝试提取此类型的凭证
18    passthrough: true   # 启用透传
19  args:
20  - name: product_id
21    description: "产品ID"
22    type: string
23    required: true
24  requestTemplate:
25    security: # MCP Server -> 后端 REST API 认证配置
26      id: BackendApiKey # 后端API需要此方案。透传的凭证将按此方案应用。
27    url: "https://api.example.com/products/{{.args.product_id}}"
28    method: GET

工作流程:

MCP Client 发起请求到 MCP Server 的 get-product-securely 工具，并在 Authorization 头中携带 Bearer <client_token>。
MCP Server 根据 tools[].security (id: ClientSideBearer) 识别出客户端使用的是 Bearer Token。它会从请求中提取 <client_token> 并移除原始的 Authorization 头。
因为 passthrough: true，提取出的 <client_token> 被标记为透传凭证。
MCP Server 准备调用后端 REST API。它查看 requestTemplate.security (id: BackendApiKey)。
由于启用了透传，MCP Server 将之前提取的 <client_token> 作为凭证值，按照 BackendApiKey 方案（即作为名为 X-API-Key 的 HTTP Header）添加到对 https://api.example.com/products/... 的请求中。
后端 REST API 收到请求，其中 X-API-Key Header 的值为 <client_token>。

注意事项:

当 tools[].security.passthrough 为 true 时，requestTemplate.security.credential 字段会被忽略，优先使用透传的凭证。
透传的凭证值会直接用于 requestTemplate.security 指定的认证方案。请确保凭证的格式与目标认证方案兼容。extractAndRemoveIncomingCredential 函数会尝试提取核心凭证部分（例如，Bearer token 值，Basic auth 的 base64 编码部分）。

服务器级别默认认证配置

为了简化配置和确保一致性，本 YAML 配置支持在服务器级别设置默认的认证配置。这些默认配置将应用于所有工具和非工具特定的接口（如 tools/list）。

`server.defaultDownstreamSecurity`

定义客户端到网关的默认认证配置。这个配置将应用于：

所有没有明确配置 security 字段的工具
tools/list 请求（获取工具列表）
其他非工具特定的 MCP 协议接口

配置字段：

id：引用 server.securitySchemes 中定义的认证方案 ID
passthrough：是否启用透明认证（可选，默认为 false）

`server.defaultUpstreamSecurity`

定义网关到后端的默认认证配置。这个配置将应用于：

所有没有明确配置 requestTemplate.security 字段的工具
tools/list 等需要访问后端服务的请求

配置字段：

id：引用 server.securitySchemes 中定义的认证方案 ID
credential：覆盖默认凭证（可选）

优先级规则

认证配置的优先级从高到低：

工具级别配置（tools[].security 和 tools[].requestTemplate.security）
服务器级别默认配置（server.defaultDownstreamSecurity 和 server.defaultUpstreamSecurity）
认证方案中的默认凭证（server.securitySchemes[].defaultCredential）

使用场景

服务器级别默认认证特别适用于以下场景：

统一认证策略：所有工具都使用相同的认证方式
MCP 代理服务器：需要为 tools/list 等非工具特定请求提供认证
简化配置：减少每个工具重复配置相同的认证信息

参数类型支持

HTTP 转 MCP 工具支持多种参数类型，使您可以更精确地定义工具参数：

string: 字符串类型（默认）
number: 数字类型（浮点数）
integer: 整数类型
boolean: 布尔类型（true/false）
array: 数组类型，使用 items 字段定义数组元素的模式
object: 对象类型，使用 properties 字段定义对象属性的模式

示例：

Plain Text

1args:
2- name: query
3  description: "搜索关键词"
4  type: string
5  required: true
6- name: limit
7  description: "返回结果数量"
8  type: integer
9  default: 10
10- name: filters
11  description: "过滤条件"
12  type: object
13  properties:
14    category:
15      type: string
16      enum: ["food", "hotel", "attraction"]
17    price:
18      type: integer
19      minimum: 0
20- name: coordinates
21  description: "坐标点列表"
22  type: array
23  items:
24    type: object
25    properties:
26      lat:
27        type: number
28      lng:
29        type: number

参数位置控制

HTTP 转 MCP 的工具支持通过 position 字段精确控制每个参数在请求中的位置。这使您可以更灵活地构建 API 请求，例如同时使用路径参数、查询参数和请求体参数。

支持的位置类型

query: 参数将作为查询参数添加到 URL 中
path: 参数将替换 URL 中的路径占位符，例如 /pet/{petId} 中的 {petId}
header: 参数将作为 HTTP 头添加到请求中
cookie: 参数将作为 Cookie 添加到请求中
body: 参数将添加到请求体中（根据内容类型自动格式化为 JSON 或表单）

使用示例

Plain Text

1args:
2- name: petId
3  description: "宠物ID"
4  type: string
5  required: true
6  position: path
7- name: token
8  description: "认证令牌"
9  type: string
10  required: true
11  position: header
12- name: sessionId
13  description: "会话ID"
14  type: string
15  position: cookie
16- name: limit
17  description: "返回结果数量"
18  type: integer
19  default: 10
20  position: query
21- name: tags
22  description: "标签列表"
23  type: array
24  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 的参数都将被忽略，以避免冲突。

请求参数传递方式

除了使用 position 精确控制每个参数的位置外，HTTP 转 MCP 的工具还支持四种批量参数处理方式，这些选项是互斥的，只能选择其中一种：

body: 使用模板手动构建请求体。这是最灵活的方式，允许您完全控制请求体的格式。

Plain Text

1requestTemplate:
2  body: |
3    {
4      "query": "{{.args.query}}",
5      "filters": {{toJson .args.filters}},
6      "options": {
7        "limit": {{.args.limit}}
8      }
9    }

argsToJsonBody: 当设置为 true 时，未指定 position 的参数将直接作为 JSON 对象发送到请求体中，并自动添加 Content-Type: application/json; charset=utf-8 头。

Plain Text

1requestTemplate:
2  argsToJsonBody: true

argsToUrlParam: 当设置为 true 时，未指定 position 的参数将作为查询参数添加到 URL 中。

Plain Text

1requestTemplate:
2  argsToUrlParam: true

argsToFormBody: 当设置为 true 时，未指定 position 的参数将以 application/x-www-form-urlencoded 格式编码在请求体中，并自动添加相应的 Content-Type 头。

Plain Text

1requestTemplate:
2  argsToFormBody: true

这些选项简化了常见 API 调用模式的配置，无需手动构建请求体或 URL 参数。请注意，这四个选项是互斥的，在一个工具配置中只能使用其中一种。如果同时配置了多个选项，系统会报错并拒绝加载该工具配置。

模板语法

HTTP 转 MCP 功能使用 GJSON Template 库进行模板渲染，它结合了 Go 的模板语法和 GJSON 的强大路径语法：

请求模板

用于构造 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 函数：

Plain Text

1<!-- 使用 gjson 函数进行复杂查询 -->
2活跃用户: {{gjson "users.#(active==true)#.name"}}
3
4<!-- 带有多个条件的数组过滤 -->
530岁以上的活跃开发者: {{gjson "users.#(active==true && age>30)#.name"}}
6
7<!-- 使用修饰符 -->
8用户名（倒序）: {{gjson "users.@reverse.#.name"}}
9
10<!-- 迭代过滤结果 -->
11管理员:
12{{range $user := gjson "users.#(roles.#(==admin)>0)#"}}
13  - {{$user.name}} ({{$user.age}})
14{{end}}

完整的 GJSON 路径语法参考可查看 GJSON 文档。

配置示例

基础配置示例：转换高德地图 API

Plain Text

1server:
2  name: rest-amap-server
3  config:
4    apiKey: your-api-key-here
5tools:
6- name: maps-geo
7  description: "将详细的结构化地址转换为经纬度坐标。支持对地标性名胜景区、建筑物名称解析为经纬度坐标"
8  args:
9  - name: address
10    description: "待解析的结构化地址信息"
11    type: string
12    required: true
13  - name: city
14    description: "指定查询的城市"
15    type: string
16    required: false
17  - name: output
18    description: "输出格式"
19    type: string
20    enum: ["json", "xml"]
21    default: "json"
22  requestTemplate:
23    url: "https://restapi.amap.com/v3/geocode/geo"
24    method: GET
25    argsToUrlParam: true
26    headers:
27    - key: x-api-key
28      value: "{{.config.apiKey}}"
29  responseTemplate:
30    body: |
31      # 地理编码信息
32      {{- range $index, $geo := .geocodes }}
33      ## 地点 {{add $index 1}}
34
35      - **国家**: {{ $geo.country }}
36      - **省份**: {{ $geo.province }}
37      - **城市**: {{ $geo.city }}
38      - **城市代码**: {{ $geo.citycode }}
39      - **区/县**: {{ $geo.district }}
40      - **街道**: {{ $geo.street }}
41      - **门牌号**: {{ $geo.number }}
42      - **行政编码**: {{ $geo.adcode }}
43      - **坐标**: {{ $geo.location }}
44      - **级别**: {{ $geo.level }}
45      {{- end }}

此配置将高德地图的地理编码 API 转换为 AI 可调用的工具。当 AI 调用此工具时：

使用提供的地址和城市参数构建 API 请求
调用高德地图 API
将 JSON 响应转换为易于阅读的 Markdown 格式
将格式化后的结果返回给 AI 助手

高级配置示例：带有条件逻辑的复杂响应处理

Plain Text

1server:
2  name: weather-api-server
3  config:
4    apiKey: your-weather-api-key
5tools:
6- name: get-weather
7  description: "获取指定城市的天气预报信息"
8  args:
9  - name: city
10    description: "城市名称"
11    type: string
12    required: true
13  - name: days
14    description: "天数(1-7)"
15    type: integer
16    required: false
17    default: 3
18  - name: include_hourly
19    description: "是否包含每小时预报"
20    type: boolean
21    default: true
22  requestTemplate:
23    url: "https://api.weatherapi.com/v1/forecast.json"
24    method: GET
25    argsToUrlParam: true
26    headers:
27    - key: x-api-key
28      value: "{{.config.apiKey}}"
29  responseTemplate:
30    body: |
31      # {{.location.name}}, {{.location.country}} 天气预报
32
33      **当前温度**: {{.current.temp_c}}°C
34      **体感温度**: {{.current.feelslike_c}}°C
35      **天气状况**: {{.current.condition.text}}
36      **湿度**: {{.current.humidity}}%
37      **风速**: {{.current.wind_kph}} km/h
38
39      ## 未来预报
40      {{range $index, $day := .forecast.forecastday}}
41      ### {{$day.date}} ({{dateFormat "Monday" $day.date_epoch | title}})
42      
43      {{if gt $day.day.maxtemp_c 30}}**高温预警!**{{end}}
44      {{if lt $day.day.mintemp_c 0}}**低温预警!**{{end}}
45      
46      - **最高温度**: {{$day.day.maxtemp_c}}°C
47      - **最低温度**: {{$day.day.mintemp_c}}°C
48      - **降水概率**: {{$day.day.daily_chance_of_rain}}%
49      - **天气状况**: {{$day.day.condition.text}}
50      
51      #### 分时预报
52      {{range $hour := slice $day.hour 6 24 3}}
53      - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
54      {{end}}
55      {{end}}

此示例展示了：

使用条件语句 (if) 进行温度警告
使用日期格式化函数 (dateFormat)
使用数组切片 (slice) 选择特定时间的天气
嵌套循环遍历多天和多时段的天气数据

使用 PrependBody 和 AppendBody 的示例：OpenAPI 转换

当您想保留原始 API 响应但添加额外的上下文信息时，prependBody 和 appendBody 字段非常有用。这在将 OpenAPI/Swagger 规范转换为 MCP 工具时特别有价值，因为您可以保留原始 JSON 响应，同时为 AI 助手提供字段含义的说明。

Plain Text

1server:
2  name: product-api-server
3  config:
4    apiKey: your-api-key-here
5tools:
6- name: get-product
7  description: "获取产品详细信息"
8  args:
9  - name: product_id
10    description: "产品ID"
11    type: string
12    required: true
13  requestTemplate:
14    url: "https://api.example.com/products/{{.args.product_id}}"
15    method: GET
16    headers:
17    - key: Authorization
18      value: "Bearer {{.config.apiKey}}"
19  responseTemplate:
20    prependBody: |
21      # 产品信息
22      
23      以下是产品的详细信息，以JSON格式返回。字段说明：
24      
25      - **id**: 产品唯一标识符
26      - **name**: 产品名称
27      - **description**: 产品描述
28      - **price**: 产品价格（美元）
29      - **category**: 产品类别
30      - **inventory**: 库存信息
31        - **quantity**: 当前库存数量
32        - **warehouse**: 仓库位置
33      - **ratings**: 用户评分列表
34        - **score**: 评分（1-5）
35        - **comment**: 评论内容
36      
37      原始JSON响应：
38      
39    appendBody: |
40      
41      您可以使用这些信息来了解产品的详细信息、价格、库存状态和用户评价。

此示例展示了：

使用 prependBody 在原始 JSON 响应前添加字段说明
使用 appendBody 在响应末尾添加使用建议
保留原始 JSON 响应，使 AI 助手可以直接访问所有数据

使用 errorResponseTemplate自定义错误响应的示例

errorResponseTemplate用于在HTTP响应status code>=300 || <200时自定义响应转换模板。支持通过_headers访问map结构的header key value, 以便在errorResponseTemplate中引用header中的值自定义错误响应结果。

Plain Text

1server:
2  config:
3    appCode: ""
4  name: "银行卡二三四要素"
5tools:
6- args:
7  - description: "银行卡号"
8    name: "cardno"
9    position: "query"
10    required: true
11    type: "string"
12  - description: "姓名（注意UrlEncode编码）"
13    name: "name"
14    position: "query"
15    required: false
16    type: "string"
17  - description: "预留手机号"
18    name: "mobile"
19    position: "query"
20    required: false
21    type: "string"
22  - description: "身份证号码"
23    name: "idcard"
24    position: "query"
25    required: false
26    type: "string"
27  description: "验证卡号、姓名、手机号、证件号是否一致"
28  errorResponseTemplate: |-
29    statusCode: {{gjson "_headers.\\:status"}}
30    errorCode: {{gjson "_headers.x-ca-error-code"}}
31    data: {{.data.value}}
32  name: "银行卡二三四要素验证"
33  requestTemplate:
34    argsToFormBody: false
35    argsToJsonBody: false
36    argsToUrlParam: true
37    method: "GET"
38    url: "https://ckid.market.xxx.com/lundear/verifyBank"
39  responseTemplate:
40    appendBody: |2-
41        - 以下是返回参数说明
42        - 参数名称: code, 参数类型: integer, 参数描述: 响应状态码
43        - 参数名称: desc, 参数类型: string, 参数描述: 描述信息
44        - 参数名称: data, 参数类型: object, 参数描述: 无描述
45        - 参数名称: data.bankId, 参数类型: string, 参数描述: 银行编码
46        - 参数名称: data.bankName, 参数类型: string, 参数描述: 银行名称
47        - 参数名称: data.abbr, 参数类型: string, 参数描述: 银行英文缩写
48        - 参数名称: data.cardName, 参数类型: string, 参数描述: 卡名称
49        - 参数名称: data.cardType, 参数类型: string, 参数描述: 卡类型
50        - 参数名称: data.cardBin, 参数类型: string, 参数描述: 卡bin
51        - 参数名称: data.binLen, 参数类型: integer, 参数描述: 卡bin长度
52        - 参数名称: data.area, 参数类型: string, 参数描述: 卡所在地区
53        - 参数名称: data.bankPhone, 参数类型: string, 参数描述: 银行电话
54        - 参数名称: data.bankUrl, 参数类型: string, 参数描述: 银行网址
55        - 参数名称: data.bankLogo, 参数类型: string, 参数描述: 银行logo

此示例展示了：

{{gjson "_headers.:status"}} -> 访问HTTP响应code
{{gjson "_headers.x-ca-error-code"}} -> 访问Header中"x-ca-error-code"的值
{{.data.value}} -> 访问响应体 (e.g., JSON 字段 "data.value")

AI 提示词生成模板

在与 AI 助手一起生成 HTTP 转 MCP 配置的模板时，您可以使用以下提示词：

Plain Text

1请帮我创建一个 AI 原生网关 的 MCP 服务器配置。支持：
21. **HTTP 转 MCP 服务器**：将 REST API 转换为 MCP 工具
3
4## 配置格式
5
6### HTTP 转 MCP 服务器配置
7
8```yaml
9server:
10  name: rest-api-server
11  type: rest  # 可选，默认为 rest
12  config:
13    apiKey: 您的API密钥
14  # 服务器级别默认认证（可选）
15  defaultDownstreamSecurity:
16    id: ClientAuth
17  defaultUpstreamSecurity:
18    id: BackendAuth
19  securitySchemes:
20  - id: ClientAuth
21    type: http
22    scheme: bearer
23  - id: BackendAuth
24    type: apiKey
25    in: header
26    name: X-API-Key
27    defaultCredential: 您的后端API密钥
28tools:
29- name: tool-name
30  description: "详细描述这个工具的功能"
31  security: # 工具级别客户端认证（可选，覆盖服务器默认）
32    id: ClientAuth
33    passthrough: true  # 启用透明认证
34  args:
35  - name: arg1
36    description: "参数1的描述"
37    type: string  # 可选类型: string, number, integer, boolean, array, object
38    required: true
39    position: path  # 可选位置: query, path, header, cookie, body
40  - name: arg2
41    description: "参数2的描述"
42    type: integer
43    required: false
44    default: 10
45    position: query
46  requestTemplate:
47    url: "https://api.example.com/endpoint"
48    method: POST
49    security: # 工具级别后端认证（可选，覆盖服务器默认）
50      id: BackendAuth
51      credential: "特定工具的凭证"  # 可选，覆盖默认凭证
52    # 以下四个选项互斥，只能选择其中一种
53    argsToUrlParam: true  # 将参数添加到URL查询参数
54    # 或者其他选项...
55    headers:
56    - key: x-api-key
57      value: "{{.config.apiKey}}"
58  responseTemplate:
59    body: |
60      # 结果
61      {{- range $index, $item := .items }}
62      ## 项目 {{add $index 1}}
63      - **名称**: {{ $item.name }}
64      - **值**: {{ $item.value }}
65      {{- end }}

模板语法

模板使用 GJSON Template 语法 https://github.com/tidwall/gjson，该语法结合了 Go 模板和 GJSON 路径语法进行 JSON 处理。模板引擎支持：

基本点表示法访问字段：{{.fieldName}}
用于复杂查询的 gjson 函数：{{gjson "users.#(active==true)#.name"}}
所有 Sprig 模板函数（类似 Helm）：{{add}}、{{upper}}、{{lower}}、{{date}} 等
控制结构：{{if}}、{{range}}、{{with}} 等
变量赋值：{{$var := .value}}

对于复杂的 JSON 响应，请考虑使用 GJSON 强大的过滤和查询能力来提取和格式化最相关的信息。

评价此篇文章

有帮助没帮助

创建 MCP 服务

消费者管理

百度智能云

AI原生网关 AIGW

AI原生网关 AIGW

HTTP 转 MCP 配置说明

快速开始：自定义 YAML 结构示例

HTTP 转 MCP 配置

认证与安全

定义认证方案 (`server.securitySchemes`)

在工具中应用认证方案

透明认证 (Passthrough Authentication)

服务器级别默认认证配置

`server.defaultDownstreamSecurity`

`server.defaultUpstreamSecurity`

优先级规则

使用场景

参数类型支持

参数位置控制

支持的位置类型

使用示例

与批量参数处理选项的关系

请求参数传递方式

模板语法

请求模板

响应模板

GJSON 路径语法

配置示例

基础配置示例：转换高德地图 API

高级配置示例：带有条件逻辑的复杂响应处理

使用 PrependBody 和 AppendBody 的示例：OpenAPI 转换

使用 errorResponseTemplate自定义错误响应的示例

AI 提示词生成模板

模板语法

AI原生网关 AIGW

HTTP 转 MCP 配置说明

快速开始：自定义 YAML 结构示例

HTTP 转 MCP 配置

认证与安全

定义认证方案 (server.securitySchemes)

在工具中应用认证方案

透明认证 (Passthrough Authentication)

服务器级别默认认证配置

server.defaultDownstreamSecurity

server.defaultUpstreamSecurity

优先级规则

使用场景

参数类型支持

参数位置控制

支持的位置类型

使用示例

与批量参数处理选项的关系

请求参数传递方式

模板语法

请求模板

响应模板

GJSON 路径语法

配置示例

基础配置示例：转换高德地图 API

高级配置示例：带有条件逻辑的复杂响应处理

使用 PrependBody 和 AppendBody 的示例：OpenAPI 转换

使用 errorResponseTemplate自定义错误响应的示例

AI 提示词生成模板

模板语法

定义认证方案 (`server.securitySchemes`)

`server.defaultDownstreamSecurity`

`server.defaultUpstreamSecurity`