1. 存量 HTTP 接口升级 MCP 协议为什么“0 改动”才是真需求如果你手上有一套跑了三五年的业务系统接口全是 RESTful 风格鉴权、限流、日志都调好了现在老板说“我们要接入 AI Agent把这些接口变成 MCP 协议服务”你第一反应大概率是又要重构一遍我试过把几个内部接口硬改成 MCP Server光是 Tool 描述、参数 Schema、SSE 长连接、鉴权透传这几件事一个接口就要写小半天接口一多根本扛不住。更麻烦的是业务代码一旦为了 MCP 改动回归测试、发版节奏、线上稳定性全都要重新评估。所以当 Nacos 发布 MCP Registry主打“存量应用接口 0 改动升级 MCP 协议”时这个点确实戳中了真实痛点。Nacos MCP Registry 的核心思路是把 MCP 的“控制面”和“数据面”拆开Nacos 当控制面负责管理 Tool 的元信息、接口描述、参数 Schema、鉴权引用Higress 当数据面负责把 MCP 协议的 JSON-RPC 请求翻译成普通 HTTP 请求转发给后端存量服务。存量服务本身不需要引入任何 MCP SDK也不需要改一行业务代码只要在 Nacos 里补一份接口描述配置Higress 就能对外暴露标准的 MCP Server。这套方案适合谁三类人最直接受益一是手里有大量存量 API、想快速接入 Agent 的后端团队二是做 AI 应用平台、需要统一管理 MCP 服务发现和灰度的架构师三是想用 Cursor、Cline 这类客户端直接调用内部接口的开发者。本文会从 Nacos 注册配置、Higress 路由规则、TaoToken 统一 Key/API 通道对接三个层面给出可复制的配置和 curl 验证步骤让你能跟着把一条存量 HTTP 接口真正跑成 MCP Tool。需要先明确一个边界Nacos 负责“描述和发现”Higress 负责“协议转换和流量治理”TaoToken 负责“统一模型与 API 通道的 Key 管理”。三者职责不重叠拼起来才是一条完整的链路。下面按落地顺序拆开讲。2. Nacos MCP Registry 与 Higress 网关的前置准备在动手写配置之前先把环境和对齐关系理清楚。Nacos MCP Registry 不是单独一个组件它是 Nacos 3.0 面向 AI 场景演进出来的能力配合 Higress 的 mcp-server 插件一起工作。你可以把它理解成Nacos 是“通讯录 说明书”Higress 是“翻译官 门卫”。先看 Nacos 侧要准备什么。用 Docker 起一个 standalone 模式最省事注意鉴权相关的环境变量必须设置否则 3.0 默认开启鉴权后会连不上export NACOS_AUTH_TOKEN$(echo -n your-secret-token-32bytes-min | base64) export NACOS_AUTH_IDENTITY_VALUEyourIdentityValue123 docker run -td \ -e PREFER_HOST_MODEhostname \ -e MODEstandalone \ -e NACOS_AUTH_IDENTITY_KEYserverIdentity \ -e NACOS_AUTH_IDENTITY_VALUE${NACOS_AUTH_IDENTITY_VALUE} \ -e NACOS_AUTH_TOKEN${NACOS_AUTH_TOKEN} \ -p 8848:8848 -p 9848:9848 \ nacos/nacos-server启动后访问http://127.0.0.1:8848/nacos默认账号密码都是 nacos能进控制台就说明 Registry 侧就绪了。再看 Higress 侧。本地验证用 Kind 起一个轻量 K8s 集群再装 Higress 是最快路径# 安装 kind [ $(uname -m) x86_64 ] curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-amd64 chmod x ./kind sudo mv ./kind /usr/local/bin/kind kind create cluster # 安装 hgctl 并部署 Higress curl -Ls https://raw.githubusercontent.com/alibaba/higress/main/tools/hack/get-hgctl.sh | bash hgctl install --set profilelocal-k8sHigress 的 MCP Server 插件依赖 Redis 做 SSE 会话状态存储所以还要起一个 Redisdocker run --name higress-redis -d redis关键一步是让 Higress 连上 Nacos通过修改 ConfigMap 完成。执行kubectl -n higress-system edit cm higress-config在data.higress里增加mcpServer段mcpServer: sse_path_suffix: /sse enable: true redis: address: 192.168.1.100:6379 match_list: - match_rule_domain: * match_rule_path: /registry match_rule_type: prefix servers: - name: nacos-registry type: nacos-mcp-registry path: /registry config: serverAddr: 192.168.1.100 namespace: serviceMatcher: amap: .* ip: .*这里的serverAddr和redis.address都要换成你本机的实际 IP用ifconfig eth0 | grep inet | awk {print $2}能拿到。serviceMatcher决定了哪些 Nacos 服务会被暴露成 MCP Tool支持正则匹配。到这一步控制面和数据面的连接就打通了。接下来才是真正体现“0 改动”的地方存量接口只需要在 Nacos 里补描述不用碰代码。3. 可复制配置Nacos 服务注册与 Higress 路由规则这一节是全文最核心的部分所有配置都可以直接复制改参数使用。我以高德开放平台的天气接口为例演示如何把restapi.amap.com这个存量 HTTP 服务0 改动变成 MCP Tool。第一步在 Nacos 里用持久化服务发现注册高德域名。注意ephemeralfalse持久化实例不会因为心跳丢失被剔除curl -X POST http://127.0.0.1:8848/nacos/v1/ns/instance?serviceNameamapgroupNameamapiprestapi.amap.comport80ephemeralfalse执行完在控制台服务列表里能看到 amap 服务下实例数为 1。第二步在配置中心新建 DataId 为amap-mcp-tools.json、分组为amap的配置。这份 JSON 就是 MCP Tool 的“说明书”Higress 会读它来生成 tool/list 和 tool/call{ protocol: http, tools: [ { name: get_weather, description: get weather by city adcode, inputSchema: { type: object, properties: { city: { type: string, description: city adcode } } } }, { name: get_adcode, description: get adcode via address, inputSchema: { type: object, properties: { address: { type: string, description: address } } } } ], toolsMeta: { get_weather: { credentialRef: amap-key.json, InvokeContext: { path: /v3/weather/weatherInfo, method: GET } }, get_adcode: { credentialRef: amap-key.json, InvokeContext: { path: /v3/geocode/geo, method: GET } } } }这里有几个字段必须对齐tools[].name是暴露给模型的 Tool 名toolsMeta里的 key 必须和它一致InvokeContext.path是后端真实 HTTP 路径credentialRef指向鉴权配置。第三步新建 DataId 为amap-key.json、分组为amap的鉴权配置。这样 API Key 不会硬编码在 Tool 描述里Nacos 还支持敏感信息加密{ type: fixed-query-token, credentialsMap: { key: key, value: 你申请到的高德API Key } }fixed-query-token表示把 key 作为 query 参数拼到请求上Higress 会自动处理后端接口完全无感知。第四步如果你还想让 Agent 能查当前出口 IP再注册一个 ipinfo.io 服务配置方式完全一样curl -X POST http://127.0.0.1:8848/nacos/v1/ns/instance?serviceNameipgroupNameipipipinfo.ioport80ephemeralfalse对应 DataIdip-mcp-tools.json、分组ip{ protocol: http, tools: [ { name: get_current_ip_address, description: get current callers ip address, inputSchema: { type: object, properties: { empty_args: { type: string, description: should be empty } } } } ], toolsMeta: { get_current_ip_address: { InvokeContext: { path: /, method: GET } } } }到这里Nacos 侧的注册和描述就完成了。Higress 的serviceMatcher里配了amap: .*和ip: .*所以这两个服务的 Tool 会自动被聚合到/registry/sse这个 MCP Server 端点下。整个过程高德和 ipinfo 的接口一行代码都没改。注意toolsMeta里的InvokeContext大小写敏感写成invokeContext会导致 Tool 调用时报找不到上下文。这个坑我在调试时踩过日志里只会提示 tool call failed不会直接告诉你字段名错了。4. 验证请求curl 跑通 MCP 服务发现与 Tool 调用配置写完不代表生效必须验证。MCP 协议基于 JSON-RPC 2.0走 SSE 传输所以验证分两步先确认 SSE 端点能连上再确认 tool/list 能返回 Tool 列表。先验证 SSE 端点。Higress 暴露的 MCP Server 地址是http://localhost/registry/sse用 curl 带 SSE 头请求curl -N -H Accept: text/event-stream http://localhost/registry/sse正常会返回类似这样的流式响应endpoint后面跟的是后续 JSON-RPC 请求要 POST 的地址event: endpoint data: /registry/message?sessionIdxxxx-xxxx-xxxx拿到 sessionId 后就可以发 tool/list 请求了。注意 Content-Type 必须是application/jsoncurl -X POST http://localhost/registry/message?sessionIdxxxx-xxxx-xxxx \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }如果配置正确返回的 result.tools 里应该能看到get_weather、get_adcode、get_current_ip_address三个 Tool每个都带 description 和 inputSchema。这一步成功说明 Nacos 的描述被 Higress 正确读取并转换成了 MCP 协议格式。接着验证 tool/call实际调用一次天气查询curl -X POST http://localhost/registry/message?sessionIdxxxx-xxxx-xxxx \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: get_weather, arguments: { city: 110000 } } }Higress 会把这次 JSON-RPC 调用翻译成GET http://restapi.amap.com/v3/weather/weatherInfo?city110000key你的Key拿到结果后再包装成 MCP 标准返回。你会在响应里看到高德返回的天气 JSON被塞进result.content里。在 Cursor 里配置就更直观了设置里加{ mcpServers: { nacos-registry: { url: http://localhost/registry/sse } } }保存后 Cursor 会自动拉取 Tool 列表你问“今天北京天气怎么样”Agent 会先调get_current_ip_address拿出口 IP再调get_adcode换 adcode最后调get_weather拿天气。整条链路里高德接口零改动全靠 Nacos 描述 Higress 转换。如果你希望模型侧也统一走一个通道可以在 TaoToken 的模型对话里把 MCP Server 挂上用统一的 Key 管理模型调用和 API 调用避免每个客户端各配一套密钥。模型对话入口在 https://taotoken.net/chat API 通道是 https://taotoken.net/api Key 在控制台 https://taotoken.net/console 生成接入文档在 https://taotoken.net/doc 。这样 Agent 调模型和调 MCP Tool 用的是同一套凭证体系排查问题时链路更清晰。5. 本篇常见错误排查401、local proxy failed 与 reading choices配置类教程最怕的就是“照着做但报错”。这一节把 Nacos Higress MCP 链路上最容易撞的几类错误列出来对照日志定位。401 Unauthorized。这个最常见分两种来源。一种是 Nacos 侧3.0 默认开启鉴权如果你 Docker 启动时没设NACOS_AUTH_TOKEN和NACOS_AUTH_IDENTITY_VALUE控制台能进但 API 注册会 401。另一种是 Higress 连 Nacos 时serverAddr或 namespace 配错ConfigMap 里namespace: 表示 public 命名空间如果你把服务注册到了别的 namespace这里必须同步改。排查方法kubectl -n higress-system logs看 higress-controller 日志里有没有nacos auth failed。local proxy failed。这个报错通常出现在 Higress 转发到后端服务时。原因一般是 Nacos 里注册的实例 IP 或端口不对或者后端服务本身不可达。比如你把restapi.amap.com注册成了内网 IPHigress 在集群里根本解析不到。排查顺序先在 Higress Pod 里curl一下注册的地址确认网络通再检查serviceMatcher的正则有没有匹配上服务名amap: .*匹配的是服务名包含 amap 的如果你服务名是amap-api也能匹配但写成^amap$就只匹配完全相等的。reading choices 相关报错。这类错误一般出现在客户端侧比如 Cursor 或 Cline 解析 MCP 返回时发现result.content结构不符合预期。MCP 协议要求 tool/call 返回的 content 是数组每项有 type 和 text。如果 Higress 转换时后端返回的是非 JSON 格式比如 XML 或纯文本而插件没做包装客户端就会报 reading choices 失败。解决办法是在 Nacos 的 Tool 描述里确认protocol: http并检查后端返回的 Content-Type。Nacos 支持把 JSON 返回转成 XML 给模型这个开关在描述配置里控制别配反了。OAuth / 鉴权透传失败。如果你的存量接口需要 Bearer Token 而不是 query keycredentialRef的 type 要改成fixed-header-token或对应的类型credentialsMap里配 header 名和值。配成fixed-query-token但后端只认 header就会一直 401。这个错误 Higress 日志里会显示upstream returned 401但不会告诉你鉴权方式配错了需要自己对照接口文档。Tool 列表为空。SSE 连上了但 tool/list 返回空数组。九成是 Nacos 配置的 DataId 或分组和 Higress 的serviceMatcher对不上。Higress 是按“服务名 分组”去 Nacos 找{serviceName}-mcp-tools.json这个 DataId 的。你服务名是 amap、分组是 amapDataId 就必须是amap-mcp-tools.json、分组amap。差一个字符都读不到。提示调试阶段建议把 Higress 的日志级别调到 debugkubectl -n higress-system edit deploy higress-controller里加--log-leveldebug能看到每次 tool/list 请求实际去 Nacos 拉了哪些配置定位效率高很多。6. 统一接入用 TaoToken 管理 MCP 与模型调用的 Key 通道把存量接口变成 MCP Tool 只是第一步真正跑起来之后你会发现另一个问题Agent 既要调模型又要调一堆 MCP Server每个服务的 Key、Base URL、鉴权方式都不一样散落在各个客户端的配置文件里换台机器就要重配一遍。这时候用 TaoToken 做统一接入层会省很多事。它的定位是统一模型与 API 通道的 Key 管理你可以把模型调用和 MCP 相关的 API 调用都收敛到一套凭证体系下。具体做法是在控制台生成一个 Key然后在需要的地方统一引用。对于长期跑编码任务或 Agent 的场景Coding Plan 更适合它面向的是持续性的编码和 Agent 调用不用每次单独配模型。入口在 https://taotoken.net/coding-plan 。如果你只是想先验证模型能不能正常调通用模型对话页面最快https://taotoken.net/chat 输入问题就能看到返回确认通道没问题再往代码里接。API 侧的统一入口是 https://taotoken.net/api 所有兼容 OpenAI 协议的客户端都可以把 Base URL 指到这里Key 用控制台生成的。接入文档在 https://taotoken.net/doc 里面有各语言 SDK 的示例。Key 管理在 https://taotoken.net/api-keys 可以按项目或环境生成不同的 Key方便做权限隔离和用量追踪。回到 MCP 场景一个典型的组合是Cursor 通过http://localhost/registry/sse调 Nacos Higress 暴露的 MCP Tool同时把模型请求指向 TaoToken 的 API 通道。这样 Agent 的“思考”走模型通道“行动”走 MCP 通道两边的 Key 都在 TaoToken 控制台统一管理换环境时只改一个 Base URL 和 Key不用逐个客户端改配置。如果你用的是 Claude Code 这类工具TaoToken 也有对应的接入方式文档里有 ClaudeCodeAnthropic 的配置说明把 Base URL 和 Key 填进去就能用。核心逻辑是一样的模型通道和 MCP 通道分离但凭证体系统一。最后说一个实际经验MCP Tool 数量一多tool/list 返回的列表会非常长模型每次都要吃掉大量 token 去理解有哪些 Tool 可用性能和成本都会受影响。Nacos 后续的演进方向之一就是做 Tool 的圈定和过滤只把当前上下文相关的 Tool 返回给 Agent。在那之前建议你在 Nacos 的serviceMatcher里按业务域拆分别把所有服务一股脑暴露出去按需匹配能明显减少无效 Tool 的干扰。