1. 为什么要把 REST API 改造成 MCP Server手里有一套跑了两年的订单查询 REST API接口文档写得清清楚楚鉴权、限流、日志都齐了。现在想让 Claude、Cursor 这类 AI 客户端直接调用它问题就来了AI 客户端不认识你的 REST 接口它只认 MCPModel Context Protocol协议。MCP Server 就是 AI 模型与外部工具、资源交互的标准接口把 REST API 包装成 MCP 工具AI 才能像调用内置函数一样调用你的内部接口。传统做法是写一个 MCP Server 进程用 Python 或 Node 把每个 REST 接口重新实现一遍参数校验、错误处理、鉴权透传全得自己写。接口一多维护成本直线上升改一个字段要动三处代码。higress 的 mcp-server 插件提供了另一条路在网关层做协议转换把现有 REST API 通过配置映射成 MCP 工具不需要写业务代码。higress 本身是基于 Istio 和 Envoy 的云原生 API 网关集成了流量网关、微服务网关、安全网关和 AI 网关的能力支持 Go/Rust/JS 编写 Wasm 插件自带控制台和数十个通用插件。这套方案适合谁手上已有 REST API、想让 AI 客户端直接调用内部接口的开发者不想为每个接口单独写 MCP Server 的团队希望统一管理鉴权、限流、可观测性的场景。我试过用纯手写 MCP Server 的方式接三个接口光参数 schema 和错误码映射就花了大半天换成 higress 配置后同样的接口量压缩到半小时以内而且改接口只改配置不动代码。整个链路的思路是AI 客户端通过 MCP 协议发起工具调用higress 的 mcp-server 插件接收请求按配置模板把 MCP 参数转换成 REST 请求转发给后端 API再把 REST 响应按模板转回 MCP 结果。TaoToken 在这里承担统一接入的角色提供统一的 Key 和 API 通道让 AI 客户端侧的模型调用和工具调用走同一个入口省去多套凭证管理的麻烦。下面从环境准备开始一步步把这条链路跑通。2. TaoToken 前置准备与 higress 环境搭建先说 TaoToken 这一侧。TaoToken 是统一接入层提供模型对话和 API 通道能力官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要先拿到一个 API Key后续在 higress 配置里作为上游鉴权凭证使用。获取 Key 的入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果你还没决定用哪个模型可以先在模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期做编码和 Agent 场景的话Coding Plan 页面有更细的说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。拿到 Key 之后记下三个东西Base URL 填 https://taotoken.net/api API Key 填你申请到的那串Model ID 填你要用的模型标识。这三件套在后面配置 MCP 工具的上游请求头时会用到。注意 Base URL 不要加 UTM 参数API 调用地址就是纯 https://taotoken.net/api 。higress 这一侧你需要一个可运行的 higress 实例。本地快速体验可以用 Docker 方式拉起生产环境建议用 Kubernetes 部署。这里以 Docker 单机模式为例方便你跟着做。先确认 Docker 版本在 20.10 以上然后拉取 higress 镜像并启动docker run -d --name higress-ai \ -p 8001:8001 \ -p 8080:8080 \ -p 8443:8443 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest启动后访问 http://localhost:8001 进入控制台默认账号密码在容器日志里用docker logs higress-ai可以看到。控制台里需要先创建一个网关实例再配置路由和插件。mcp-server 插件是内置插件不需要额外安装在插件市场里能找到。这里有个容易踩的坑higress 的 mcp-server 插件执行阶段是默认阶段优先级 30。如果你同时装了其他修改请求的插件注意优先级顺序避免请求体被提前改写导致模板渲染失败。另外REST-to-MCP 场景下 server.name 字段可以自定义不像内置 MCP Server比如 quark-search那样必须用固定名称。自定义名称会作为 MCP 工具的前缀暴露给 AI 客户端建议用有意义的英文短名比如order-api、user-svc这种。环境就绪后确认后端 REST API 可达。假设你有一个订单查询接口GET https://api.internal.example.com/v1/orders支持order_id和status两个查询参数。先在 higress 所在网络里用 curl 测一下连通性确保网关能访问到后端。如果后端在内网注意 higress 容器的网络模式必要时用 host 网络或配置 DNS。3. 可复制的 higress MCP 配置片段这一节给出完整的配置片段你可以直接复制到 higress 控制台的插件配置里。mcp-server 插件的配置分两部分Server 配置和 REST-to-MCP 工具配置。Server 配置里server.name必填server.config选填用于放 API 密钥等server.allowTools选填用于限制允许调用的工具列表。工具配置里每个工具需要name、description、args、requestTemplate、responseTemplate。先看一个最小可用的 JSON 配置把订单查询接口映射成 MCP 工具{ server: { name: order-api, config: { apiKey: your-taotoken-api-key } }, tools: [ { name: query-order, description: 根据订单号查询订单详情支持按状态过滤, args: [ { name: order_id, description: 订单号必填, type: string, required: true }, { name: status, description: 订单状态过滤, type: string, required: false, enum: [pending, paid, shipped, closed], default: paid } ], requestTemplate: { url: https://api.internal.example.com/v1/orders, method: GET, headers: [ { key: Authorization, value: Bearer {{.config.apiKey}} } ], argsToUrlParam: true }, responseTemplate: { body: {{.}} } } ] }这段配置里几个关键点。server.config.apiKey放的是 TaoToken 的 Key在请求模板里通过{{.config.apiKey}}引用。argsToUrlParam: true表示把工具参数作为查询参数拼到 URL 上适合 GET 接口。responseTemplate.body用{{.}}表示原样返回响应体你也可以用 GJSON 路径提取字段比如{{.data.order_id}}。如果你的接口是 POST 且需要 JSON 请求体把argsToUrlParam换成argsToJsonBody: true插件会自动添加Content-Type: application/json; charsetutf-8头。需要手动构建复杂请求体时用body字段配合 GJSON Template 语法requestTemplate: { url: https://api.internal.example.com/v1/orders/search, method: POST, headers: [ { key: Authorization, value: Bearer {{.config.apiKey}} }, { key: Content-Type, value: application/json } ], body: {\query\: \{{.args.query}}\, \filters\: {{toJson .args.filters}}, \options\: {\limit\: {{.args.limit}}}} }注意body、argsToJsonBody、argsToUrlParam、argsToFormBody这四个是互斥的只能选一个。表单提交场景用argsToFormBody: true插件会自动编码成application/x-www-form-urlencoded格式并设置对应 Content-Type。参数类型支持 string、number、integer、boolean、array、object 六种。array 类型用items定义元素模式object 类型用properties定义属性模式。比如一个接收标签数组的参数{ name: tags, description: 订单标签列表, type: array, required: false, items: { type: string } }模板语法用的是 GJSON Template结合了 Go 模板和 GJSON 路径语法。请求模板里访问配置值用{{.config.字段名}}访问工具参数用{{.args.参数名}}。响应模板里用 GJSON 路径访问 JSON 字段点表示法如address.city数组索引用users.0.name数组迭代用users.#.name数组过滤用users.#(age30)#.name多路径用{name:users.0.name,count:users.#}。还支持add、upper、lower等模板函数和if、range控制结构。配置写完后在控制台点保存插件会热加载生效不需要重启网关。如果配置有语法错误控制台会给出提示按提示改就行。保存成功后MCP Server 的端点会暴露在网关的/mcp路径下具体地址在控制台的插件详情页能看到。4. 端到端调用验证与成功结果配置生效后需要验证整条链路是否通。验证分两步先用 MCP 客户端直接调网关的 MCP 端点确认工具能被发现和调用再确认 REST 请求正确转发到后端并返回预期结果。第一步用 curl 模拟 MCP 的 tools/list 请求看工具是否注册成功curl -X POST http://localhost:8001/mcp \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }预期返回里能看到query-order这个工具包含 name、description 和 inputSchema。如果返回空列表检查插件的server.allowTools是否限制了工具范围或者工具配置的name字段是否为空。第二步调用工具传一个真实的订单号curl -X POST http://localhost:8001/mcp \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: query-order, arguments: { order_id: ORD20240101001, status: paid } } }预期返回里result.content数组包含后端 REST API 的响应数据。如果后端返回的是 JSONresponseTemplate.body用{{.}}时会原样透传AI 客户端能直接解析。如果只想返回部分字段把 body 改成{{.data.order_id}} {{.data.status}}这种 GJSON 路径。第三步在真实 AI 客户端里验证。以 Claude Code 为例在配置文件里加上 MCP Server 地址。Claude Code 的 MCP 配置通常在~/.claude/claude_desktop_config.json或项目级配置里格式如下{ mcpServers: { order-api: { url: http://localhost:8001/mcp, transport: http } } }保存后重启 Claude Code在对话里输入「帮我查一下订单 ORD20240101001 的状态」AI 会调用query-order工具返回结果会显示在对话里。如果 AI 没有调用工具检查 MCP Server 是否连接成功Claude Code 的日志里会有连接状态。实测下来从配置到端到端调通顺利的话二十分钟以内。关键卡点通常在鉴权头透传和参数映射上。后端 API 如果要求特定的鉴权头在requestTemplate.headers里加上值可以用{{.config.apiKey}}引用 TaoToken 的 Key也可以用固定字符串。如果后端要求多个头headers 数组里加多项即可。验证成功后你可以在 higress 控制台看到这次调用的可观测性数据包括请求量、延迟、状态码分布。这是网关层做协议转换的一个额外好处所有 MCP 工具调用都经过网关限流、鉴权、日志、链路追踪统一管理不需要在每个 MCP Server 里重复实现。5. 常见报错排查与修复配置过程中会遇到几类典型报错这里按实际遇到的频率排列给出排查路径和修复方法。第一类401 Unauthorized。MCP 客户端调用工具时返回 401说明上游 REST API 的鉴权没通过。检查requestTemplate.headers里的 Authorization 头是否正确引用了{{.config.apiKey}}确认server.config.apiKey里填的 TaoToken Key 没有多余空格。如果后端用的是其他鉴权方式比如X-API-Key把 header 的 key 改成对应名称。还有一种情况是 TaoToken Key 本身失效去控制台 API Keys 页面确认 Key 状态https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。第二类local proxy failed。这个报错通常出现在 higress 转发请求到后端时表示网关无法连接到后端 API。排查顺序先在 higress 容器里 curl 后端地址确认网络可达检查后端地址是否写错特别是 https 和 http 混用如果后端在内网确认 higress 的网络模式能访问内网。Docker 模式下如果后端跑在宿主机上用host.docker.internal代替localhost。第三类reading choices 相关报错。这个报错一般出现在 AI 客户端侧表示模型返回的响应格式不符合预期。检查responseTemplate.body的模板语法如果用了 GJSON 路径但路径不存在会返回空值导致客户端解析失败。先用{{.}}原样返回确认链路通了再逐步加字段提取。另外确认 TaoToken 的 Base URL 填的是 https://taotoken.net/api 不要带多余路径。第四类OAuth 相关报错。如果后端 API 用 OAuth 2.0 鉴权需要在 higress 侧配置 token 获取逻辑。简单场景可以在server.config里放一个长期 token复杂场景建议用 higress 的认证插件配合。注意 OAuth token 有过期时间过期后会返回 401需要刷新 token。如果报错信息里出现 OAuth 字样先确认 token 是否有效。第五类工具调用参数校验失败。AI 客户端传的参数类型和args里定义的不一致比如定义的是 integer 但传了字符串。检查args[].type是否和后端 API 期望的类型匹配。如果后端接受字符串形式的数字把 type 改成 string 并在 requestTemplate 里用模板函数转换。enum 类型要确保 AI 传的值在允许列表里否则会被拒绝。第六类MCP Server 连接失败。AI 客户端连不上 higress 的 MCP 端点检查端点地址是否正确端口是否开放。higress 默认 MCP 端点在 8001 端口的/mcp路径如果改了端口或路径同步更新客户端配置。防火墙和安全组也要确认放行。排查时善用 higress 控制台的日志功能每次工具调用的请求和响应都有记录能看到实际转发的 URL、请求头、请求体和响应体。这是定位问题最快的方式。如果日志里看不到请求说明请求没到网关问题在客户端侧如果看到了请求但响应异常问题在模板配置或后端 API。6. 统一接入与后续扩展把 REST API 转成 MCP 工具只是第一步真正让这套方案在生产环境跑起来还需要考虑统一接入和扩展性。TaoToken 在这里的价值是提供统一的 Key 和 API 通道AI 客户端侧的模型调用和工具调用走同一个入口省去多套凭证管理的麻烦。你可以在 TaoToken 控制台统一管理 Key 的权限和配额不用在每个 MCP Server 里单独配置鉴权。后续扩展有几个方向。一是批量转换把多个 REST 接口一次性映射成一组 MCP 工具在tools数组里加多项即可每个工具独立配置 requestTemplate 和 responseTemplate。二是用server.allowTools控制暴露给 AI 客户端的工具范围不同客户端可以配不同的 allowTools 列表实现权限隔离。三是结合 higress 的限流插件对 MCP 工具调用做细粒度的限流防止 AI 客户端高频调用打爆后端。如果你要做更复杂的参数转换比如把 AI 传的自然语言参数转成后端需要的结构化查询可以在 requestTemplate 的 body 里用 GJSON Template 的控制结构做条件判断。比如根据 status 参数的值决定是否加额外的过滤条件body: {\query\: \{{.args.query}}\{{if .args.status}}, \status\: \{{.args.status}}\{{end}}}这套方案的核心优势是把协议转换放在网关层业务代码零改动。后端 API 的维护者不需要知道 MCP 协议AI 客户端也不需要知道 REST 细节higress 在中间做翻译。对于已有大量 REST API 的团队这是接入 AI 生态成本最低的路径。需要查文档的话TaoToken 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。配置过程中遇到模板语法问题优先用{{.}}原样返回确认链路再逐步加字段提取这样定位问题最快。