Higress 网关实战：REST API 转 MCP Server 工具配置指南

Higress 是一款云原生 API 网关，集成了流量、微服务、安全及 AI 网关功能。基于 Istio 和 Envoy 开发，支持 Go/Rust/JS 等语言编写 Wasm 插件，提供开箱即用的控制台。

在 AI 场景下，Higress AI 网关支持 OpenAI、DeepSeek、通义千问等多种服务商，具备令牌限流、消费者鉴权、WAF 防护及语义缓存能力。今天重点聊聊如何利用其 MCP Server 插件，将现有的 REST API 快速转换为 AI 助手可调用的工具。

为什么需要 MCP Server 插件？

Model Context Protocol (MCP) 定义了 AI 模型与外部工具和资源交互的标准方式。通过 Higress 的 mcp-server 插件，我们可以实现以下目标：

零代码转换：无需额外开发，直接将现有 REST API 暴露为 AI 工具。
统一治理：复用网关的认证、鉴权、限流和可观测性能力，确保安全性与性能。
快速部署：利用插件机制，几分钟内即可添加新的 MCP Server。

该插件默认阶段执行，优先级设为 30，适合大多数场景。

核心配置详解

配置主要分为两部分：Server 基础信息和具体的 REST-to-MCP 工具定义。

Server 配置

这是 MCP Server 的元数据部分。

字段名	类型	必填	默认值	说明
`server.name`	string	是	-	Server 名称。内置服务（如 quark-search）只需填此项；REST 场景可自定义。
`server.config`	object	否	`{}`	服务器级配置，例如全局 API Key。
`server.allowTools`	array	否	-	允许调用的工具列表。不指定则允许所有。

REST-to-MCP 工具配置

这是最核心的部分，定义了如何将 HTTP 请求映射为 AI 工具调用。

参数定义 (`tools[].args`)

你需要明确告诉 AI 这个工具需要什么输入。支持多种类型：

string：字符串（默认）
number / integer：数字或整数
boolean：布尔值
array：数组，需配合 items 定义元素模式
object：对象，需配合 properties 定义属性模式

每个参数还可以设置 required（是否必需）、default（默认值）以及 enum（枚举值），帮助 AI 更准确地生成参数。

请求模板 (`requestTemplate`)

这里决定了如何把 AI 生成的参数变成真实的 HTTP 请求。支持四种传递方式，它们是互斥的：

JSON Body (argsToJsonBody: true)：自动添加 Content-Type: application/json，参数直接转为 JSON 体。
URL Params (argsToUrlParam: true)：参数追加到 URL 查询串中。
Form Data (argsToFormBody: true)：以 application/x-www-form-urlencoded 格式编码。
手动构建 (body)：最灵活，使用模板语法完全控制请求体内容。

响应模板 (`responseTemplate`)

AI 通常只关心结果，我们需要用 GJSON 路径语法提取关键信息返回给模型。例如 {{.body.data.result}}。

模板语法与实战技巧

Higress 使用 GJSON Template 语法，结合了 Go 模板和 GJSON 路径。这比纯正则强大得多。

访问参数：{{.args.参数名}}
访问配置：{{.config.字段名}}
处理响应：使用 GJSON 路径如 users.#(age>=30)#.name 进行过滤。

注意：在手动构建 body 时，可以使用 toJson 函数将复杂对象序列化为 JSON 字符串。

requestTemplate:
  body: |
    {
      "query": "{{.args.query}}",
      "filters": {{toJson .args.filters}},
      "options": { "limit": {{.args.limit}} }
    }

配置示例

1. 内置服务：Quark Search

如果直接使用内置的搜索服务，配置非常简单：

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

2. 自定义 REST：高德地图 API

这是一个典型的 REST-to-MCP 场景。我们将高德地理编码接口包装成一个工具。

server:
  name: rest-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://restapi.amap.com/v3/geocode/geo"
        method: GET
        argsToUrlParam: true

在这个例子中，我们使用了 argsToUrlParam: true，因为高德接口主要依赖查询参数。AI 会根据 args 的定义自动生成正确的 URL 请求。

总结

通过 Higress 网关的 MCP Server 插件，开发者无需编写额外的后端代码，就能让 AI Agent 轻松接入各种数据源。无论是简单的查询接口还是复杂的业务逻辑，只要配置得当，都能转化为 AI 可调用的工具。这不仅降低了集成门槛，还借助网关能力保障了系统的安全性和稳定性。