配置字段

服务器配置

允许的工具配置

HTTP to MCP 工具配置

认证安全

定义认证方案 (server.securitySchemes)

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

配置示例（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: "/users/{name}"
      method: GET
      security:
        id: MyBearerToken # 使用上面定义的 MyBearerToken 方案
        # credential: "override_token_for_this_tool" # 可选：为此工具覆盖默认Token
  # ...
  - name: update-inventory
    # ... 其他工具配置 ...
    requestTemplate:
      url: "/inventory/{itemId}"
      method: POST
      security:
        id: MyApiKeyInHeader # 使用 MyApiKeyInHeader 方案
        # 此工具将使用 MyApiKeyInHeader 中定义的 defaultCredential

参数类型支持

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

• string: 字符串类型（默认）。

• number: 数字类型（浮点数）。

• integer: 整数类型。

• boolean: 布尔类型（true/false）。

• array: 数组类型，使用 items 字段定义数组元素的模式。

• object: 对象类型，使用 properties 字段定义对象属性的模式。

示例：

args:
  - name: query
    description: "搜索关键词"
    type: string
    required: true
  - name: limit
    description: "返回结果数量"
    type: integer
    default: 10
  - name: filters
    description: "过滤条件"
    type: object
    properties:
      category:
        type: string
        enum: ["food", "hotel", "attraction"]
      price:
        type: integer
        minimum: 0
  - name: coordinates
    description: "坐标点列表"
    type: array
    items:
      type: object
      properties:
        lat:
          type: number
        lng:
          type: number

参数位置控制

HTTP to MCP 工具支持通过 position 字段精确控制每个参数在请求中的位置。这使您可以更灵活地构建 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 的参数都将被忽略，以避免冲突。

body的配置暂不支持模版的参数引用。

请求参数传递方式

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

• body: 暂不支持模版构建。

requestTemplate:
  body: |
    {
      "username": "blob",
      "age": 13
    }

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

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

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

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