Nacos + Higress 组合拳：存量 API 无缝升级 MCP 协议的实战指南

1. 为什么你的存量API需要一次“无痛”升级？

最近和几个做AI应用开发的朋友聊天，发现大家普遍面临一个头疼的问题：公司里积累了大量的传统HTTP API服务，现在想接入大模型，让AI Agent能直接调用这些服务，但一听说要改造成符合MCP（Model Context Protocol）协议的Server，头都大了。这意味着什么？意味着要重写接口、调整架构、重新部署，人力成本和时间成本都高得吓人。更别提那些核心业务的老代码，牵一发而动全身，谁也不敢轻易动。

我自己也经历过这个阶段。去年我们团队想把一个内部的天气查询和地理信息服务开放给AI助手使用，最初的方案就是老老实实写一个MCP Server。结果光是理解MCP协议规范、处理SSE（Server-Sent Events）连接、封装Tool的输入输出，就折腾了小半个月。这还只是一个简单服务。如果公司有上百个API呢？这改造工作量想想就让人绝望。

所以，当我第一次听说Nacos和Higress联手搞出了一个“0改动”升级MCP协议的方案时，我的第一反应是：真的假的？存量API，一行代码不用改，就能变成大模型能直接调用的工具？这听起来像是个“魔术”。但经过我自己的亲手实践和几个项目的验证，我发现这不仅是真的，而且方案非常巧妙和实用。它本质上不是让你去改造API本身，而是通过一个“协议转换层”和“元数据管理中心”，让大模型“以为”它在调用标准的MCP Server，实际上背后还是你那些运行了多年的老服务。

简单来说，这个组合拳的核心分工是这样的：

• Nacos：扮演“AI服务注册中心”或者说“MCP Registry”的角色。你不需要动业务代码，只需要在Nacos里，用描述文件的方式，告诉它你的每个API接口是干什么的（Tool描述）、需要什么参数（Input Schema）、以及如何调用（路径、方法）。Nacos负责统一管理和下发这些元数据。
• Higress：扮演“AI网关”和“协议转换器”的角色。它内置了MCP Server的能力。当AI Agent（比如Cursor、Windsurf）连接过来时，Higress会从Nacos拉取最新的Tool列表，通过标准的MCP协议暴露出去。当Agent发起调用时，Higress再将MCP格式的请求（JSON-RPC）实时转换成普通的HTTP请求，转发给你的后端API，拿到结果后再包装成MCP格式返回给Agent。

整个过程，你的业务API就像什么都没发生一样，照常接收HTTP请求，返回JSON数据。所有的“魔法”都发生在Nacos的配置管理和Higress的协议转换上。这对于那些拥有大量存量Java Spring Cloud、Dubbo服务（通常已注册在Nacos），或者任何能通过HTTP访问的API团队来说，简直是“福音”。你不需要让开发人员去学习MCP协议细节，只需要运维或架构师在Nacos里做一次性的配置，就能让整个服务集群快速具备AI能力。

2. 核心原理拆解：Nacos如何成为MCP的“大脑”？

光说“0改动”可能有点抽象，我们得深入看看这套机制到底是怎么运转的。理解了原理，你才能用得放心，出了问题也知道去哪排查。

2.1 从“人懂”到“模型懂”的关键：接口描述

我们先回想一下，人类开发者是怎么调用一个API的。比如，我们有一个查询天气的接口GET /v3/weather/weatherInfo?city=110101。我们看到这个URL，知道它需要一个叫city的参数，值是城市编码（adcode），返回的是JSON格式的天气数据。这些知识存在于我们的脑子或者API文档里。

但对于大模型来说，它是个“瞎子”。它看不到你的代码，也读不懂你的文档（除非你把文档喂给它）。它需要一套机器可读的、结构化的描述，才能知道：“哦，这里有一个叫get_weather的工具，它的作用是查询天气，它需要一个字符串类型的city参数，这个参数是城市编码。”

这就是Nacos作为MCP Registry要解决的核心问题：把你脑子里、文档里关于API的知识，结构化地存储起来。具体来说，你需要在一个JSON配置文件里（比如weather-service-mcp-tools.json）定义清楚：

{ "tools": [ { "name": "get_weather", "description": "根据城市编码查询实时天气信息", "inputSchema": { "type": "object", "properties": { "city": { "type": "string", "description": "中国国家标准城市行政区划编码，如北京为110000" } }, "required": ["city"] } } ], "toolsMeta": { "get_weather": { "credentialRef": "api-keys.json", "InvokeContext": { "path": "/v3/weather/weatherInfo", "method": "GET" } } } }

这个配置文件做了几件事：

1. 定义Tool：在tools数组里，声明了一个名为get_weather的工具，并描述了它的输入参数结构 (inputSchema)。这个结构会通过MCP协议原样暴露给AI Agent。
2. 关联调用上下文：在toolsMeta里，指定了这个工具具体对应到哪个后端API。path和method指明了HTTP调用的端点和方法。credentialRef则可能指向另一个存储API Key等认证信息的Nacos配置。

这一步，就是你唯一的“配置”工作。你不需要在天气服务的代码里加任何注解或SDK，只需要在Nacos控制台创建这个配置项。Nacos会持久化它，并通知给订阅了这些信息的Higress网关。

2.2 Higress的协议转换“魔术”

当AI Agent（MCP Client）连接到Higress网关时，会发生两件关键的事情：

第一幕：Tool列表拉取。Agent会向Higress发起初始化请求。Higress的MCP Server插件此刻会向Nacos查询所有已配置的Tool描述信息，然后将它们聚合、转换成标准的MCPtools/list响应，返回给Agent。于是，Agent的界面上就出现了get_weather这个可用的工具。

第二幕：实时调用与协议转换。当用户向AI提问“北京天气怎么样？”时，AI模型会决定调用get_weather工具，并生成调用参数{"city": "110000"}。这个调用请求以MCP的JSON-RPC格式发送给Higress。

这里就是Higress施展魔法的地方：

1. 请求解析：Higress收到tool/call请求，解析出要调用的工具名是get_weather，参数是{"city": "110000"}。
2. 元数据查询：Higress根据工具名，快速从本地缓存（数据来自Nacos）中查到对应的InvokeContext：路径是/v3/weather/weatherInfo，方法是GET。
3. 服务发现：Higress还需要知道这个请求要发给谁。它再次查询Nacos，找到名为weather-service的服务下注册的后端实例地址（比如10.1.1.100:8080）。
4. 协议组装：Higress将参数city=110000以Query String的形式，拼接到目标URL上，形成最终的HTTP请求：GET http://10.1.1.100:8080/v3/weather/weatherInfo?city=110000。
5. 请求转发与响应包装：Higress将这个普通的HTTP请求转发给后端天气服务。天气服务返回JSON数据后，Higress再把这坨JSON数据包装进MCPtool/call的响应结构里，返回给AI Agent。

整个过程中，你的后端天气服务只处理了一个最普通的HTTP GET请求，它完全感知不到调用它的是一个人、一个脚本，还是一个AI大模型。这种透明性，正是“无缝升级”的精髓。

2.3 为什么是“组合拳”？优势不止于转换

Nacos + Higress 这个组合，带来的好处远不止是协议转换。它把生产级微服务治理的能力赋能给了AI应用场景：

• 动态生效与高效调试：改一个Tool的描述，比如让description更精准，只需要在Nacos控制台修改配置并发布，Higress几乎能实时感知并更新。这比重新打包、部署一个MCP Server要快得多，方便你快速迭代和优化给AI的“提示”。
• 配置的版本与灰度：Nacos自带配置版本管理。你可以随时查看历史配置，对比差异，一键回滚。你还可以对MCP配置进行灰度发布，比如只让10%的AI流量使用新的Tool描述，观察效果后再全量，这在大模型场景下非常实用。
• 敏感信息安全管理：API Key、令牌等敏感信息，可以存储在Nacos的加密配置中。在credentialRef里引用，Higress在转发请求时会自动将其作为Header或Query参数附加，避免明文暴露在Tool描述文件里。
• 服务健康与负载均衡：你的后端服务可能有多台实例。Nacos会进行健康检查，剔除宕机实例。Higress从Nacos获取服务实例列表时，天然就获得了负载均衡和多实例冗余的能力，保证了AI调用链路的可靠性。

这套体系，相当于为你现有的微服务架构增加了一个“AI能力适配层”。你过去在服务发现、配置管理、流量治理上的投入，现在可以直接复用于AI场景，这才是真正的降本增效。

3. 实战指南：手把手将高德地图API“变成”MCP工具

理论讲得再多，不如亲手做一遍。我们就以最经典也最实用的场景为例：把高德地图的开放API（比如天气查询、地理编码）零代码改造成AI可用的工具。你可以完全跟着我的步骤来，我踩过的坑都会提前告诉你。

3.1 环境准备：三件套部署

我们需要三个核心组件：Nacos（存储配置和服务）、Higress（协议转换网关）、一个Redis（用于Higress内部缓存）。为了快速演示，我们全部使用Docker部署。

第一步：启动Nacos服务器。Nacos从2.2.0版本开始加强了鉴权，我们需要设置一个Token。打开终端，执行以下命令：

# 生成一个安全的Token（这里用简单字符串示例，生产环境应用更复杂密钥） export NACOS_AUTH_TOKEN=SecretKey0123456789 export NACOS_AUTH_IDENTITY_VALUE=your_identity_value # 使用Docker运行Nacos（单机模式） docker run -d \ --name nacos-server \ -e PREFER_HOST_MODE=hostname \ -e MODE=standalone \ -e NACOS_AUTH_IDENTITY_KEY=serverIdentity \ -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:latest

运行成功后，访问http://你的服务器IP:8848/nacos，默认账号密码是nacos/nacos，你应该能看到Nacos的控制台。

第二步：启动Redis。Higress的MCP插件需要用Redis来管理SSE连接等状态，很简单：

docker run -d --name higress-redis -p 6379:6379 redis:alpine

第三步：部署Higress。Higress的部署方式很多，这里我们用最快捷的hgctl命令行工具，它会在本地用Kind创建一个Kubernetes集群并安装Higress。

1. 安装Kind和kubectl（如果已有K8s环境可跳过）：

   # 安装Kind 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 # 创建本地K8s集群 kind create cluster --name higress-demo # 安装kubectl curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" chmod +x ./kubectl sudo mv ./kubectl /usr/local/bin/kubectl

2. 安装hgctl并部署Higress：

   # 下载hgctl curl -Ls https://raw.githubusercontent.com/alibaba/higress/main/tools/hack/get-hgctl.sh | bash # 使用本地K8s配置文件安装Higress hgctl install --profile local-k8s --set global.kubeConfig=$(echo ~)/.kube/config

   安装完成后，用kubectl get pod -n higress-system查看，看到所有Pod都是Running状态就成功了。

3.2 关键配置：让Higress连接Nacos

部署完只是有了“身体”，现在要让它们“大脑”（Nacos）和“肢体”（Higress）连通。我们需要修改Higress的一个ConfigMap。

首先，获取你本机的内网IP地址（不是127.0.0.1）。在Linux/Mac上可以运行ifconfig或ip addr查看，假设你的IP是192.168.1.100。

然后，编辑Higress的配置：

kubectl -n higress-system edit configmap higress-config

这会打开一个编辑器。找到data.higress下面的YAML配置块。我们需要在合适的位置（通常在gateway配置同级）添加mcpServer的配置。注意缩进，添加后大致结构如下：

apiVersion: v1 data: higress: | # ... 其他现有配置 ... mcpServer: sse_path_suffix: /sse enable: true redis: address: 192.168.1.100:6379 # 替换为你的Redis地址 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:8848 # 替换为你的Nacos地址 namespace: "" # Nacos命名空间，默认public留空 serviceMatcher: amap: ".*" # 服务名匹配规则，这里匹配名为amap的服务 ip: ".*" # 匹配名为ip的服务 # ... 其他现有配置 ...

关键点解释：

• redis.address：指向我们刚启动的Redis。
• servers.config.serverAddr：指向我们刚启动的Nacos。
• serviceMatcher：这是一个非常重要的过滤配置。它告诉Higress，只关心Nacos中哪些服务下的MCP配置。这里我们预先写上了amap和ip，对应我们接下来要注册的两个服务。你可以用正则表达式，比如.*匹配所有服务，但在生产环境建议按需配置，避免拉取无关数据。

保存退出后，Higress控制器会自动重新加载配置。等待十几秒，可以用kubectl logs -n higress-system deployment/higress-controller --tail=10查看日志，确认没有报错。

3.3 在Nacos中“注册”高德地图服务

高德地图的API本身是一个外部服务，我们需要在Nacos中把它“虚拟”地注册为一个服务，并附上详细的接口描述。

第一步：申请高德开放平台Key。

1. 访问高德开放平台官网，注册登录。
2. 进入「控制台」-「应用管理」，点击「创建新应用」。
3. 应用创建好后，在「Key」管理页面，为这个应用「添加Key」，类型选择「Web服务」。成功后会得到一串key=后面的字符串，保存好它，后面需要用到。

第二步：在Nacos注册服务。高德API的域名是restapi.amap.com。我们将其注册为一个名为amap、分组为amap的服务（分组名和上面ConfigMap里的serviceMatcher对应）。

curl -X POST 'http://192.168.1.100:8848/nacos/v1/ns/instance?serviceName=amap&groupName=amap&ip=restapi.amap.com&port=80&ephemeral=false'

ephemeral=false表示这是持久化实例，不会因为心跳丢失而自动删除。执行后，在Nacos控制台「服务管理」列表里，应该能看到服务amap，实例数为1。

第三步：配置高德API的MCP描述。这是最核心的一步。进入Nacos控制台「配置管理」，点击「+」新建配置。

• Data ID:amap-mcp-tools.json(这个名字可以自定义，但建议有规律)
• Group:amap(必须和上面服务分组一致！)
• 配置格式: JSON
• 配置内容：

{ "protocol": "http", "tools": [ { "name": "get_weather", "description": "根据城市编码查询实时天气信息，包括温度、湿度、风向、风力、天气状况等。", "inputSchema": { "type": "object", "properties": { "city": { "type": "string", "description": "中国国家标准城市行政区划编码（adcode），例如：北京市为110000，朝阳区为110105。可通过地理编码接口查询获得。" } }, "required": ["city"] } }, { "name": "get_adcode", "description": "根据结构化地址（如：北京市朝阳区望京街道）查询对应的地理编码（adcode）和坐标。", "inputSchema": { "type": "object", "properties": { "address": { "type": "string", "description": "完整的结构化地址，例如：广东省深圳市南山区深南大道10000号。" } }, "required": ["address"] } } ], "toolsMeta": { "get_weather": { "credentialRef": "amap-key.json", "InvokeContext": { "path": "/v3/weather/weatherInfo", "method": "GET", "paramMapping": { "city": "city" } } }, "get_adcode": { "credentialRef": "amap-key.json", "InvokeContext": { "path": "/v3/geocode/geo", "method": "GET", "paramMapping": { "address": "address" } } } } }

这个配置定义了两个工具（Tool）。paramMapping指明了MCP调用参数名到API实际参数名的映射，这里名字一样，所以简单对应。credentialRef指向另一个存储密钥的配置。

第四步：配置高德API Key。再新建一个配置：

• Data ID:amap-key.json
• Group:amap
• 配置内容：

{ "type": "fixed-query-token", "credentialsMap": { "key": "key", "value": "这里替换成你申请到的高德API Key" } }

这个配置告诉Higress，在转发请求给高德API时，需要在URL的Query参数里自动加上key=你的Key。这样就避免了在Tool描述里暴露敏感信息。

3.4 配置AI客户端（以Cursor为例）并验证

现在，MCP Server已经就绪了。我们需要一个MCP Client来连接它。这里以目前非常流行的AI代码编辑器Cursor为例。

1. 打开Cursor，进入设置（Settings）。
2. 找到Features->MCP Servers部分。
3. 点击Edit Config，会打开一个mcp.json文件。
4. 在其中添加我们的Higress MCP Server地址：

{ "mcpServers": { "nacos-registry": { "url": "http://192.168.1.100/registry/sse", "description": "通过Nacos+Higress暴露的内部API服务" } } }

注意：这里的URL端口是80（Higress网关的默认端口），路径是/registry/sse，这与我们在Higress ConfigMap中配置的match_rule_path: /registry和sse_path_suffix: /sse是对应的。

5. 保存配置文件，Cursor可能会自动重连，或者提示你重启。重启Cursor后，当你新建一个Chat会话，并切换到“Agent”模式时，理论上它就已经加载了我们刚定义的两个工具get_weather和get_adcode。

我们来做个测试：在Cursor的Agent聊天框里输入：“帮我查一下北京海淀区的天气。” 观察AI的思考过程（如果开启了相关设置）。你应该会看到类似以下的逻辑：

1. AI识别出需要查询天气，但需要城市编码。
2. 它会先尝试调用get_adcode工具，参数{"address": "北京市海淀区"}，从高德API获取到海淀区的adcode（比如110108）。
3. 然后调用get_weather工具，参数{"city": "110108"}，最终将高德返回的天气信息整理成自然语言回复给你。

整个过程，你的高德API没有做任何改动，Higress网关自动处理了协议转换、参数映射和密钥添加。这就是“0改动”升级的魅力。

4. 进阶技巧与避坑指南

按照上面的步骤走通，你已经掌握了基本流程。但在真实的生产环境中，你会遇到更多细节问题。这里分享几个我实战中总结的进阶技巧和常见坑点。

4.1 如何处理复杂的API参数映射？

上面的例子参数映射很简单。但现实中，API可能很复杂：参数可能在Path里、在Body里，甚至是多层嵌套的JSON。

场景一：路径参数（Path Variable）假设你的内部API是GET /user/{userId}/order。在InvokeContext里可以这样配置：

"InvokeContext": { "path": "/user/{{userId}}/order", "method": "GET" }

在paramMapping里，你需要告诉Higress如何提取值：

"paramMapping": { "userId": "userId" }

当MCP调用参数为{"userId": "123"}时，Higress会自动将路径中的{{userId}}替换为123。

场景二：复杂JSON Body假设你的内部API是POST /api/order，需要接收一个JSON body：{"items": [...], "address": {...}}。你希望AI通过自然语言描述订单，然后自动构造这个结构。这需要你在Tool的inputSchema里定义非常清晰、嵌套的结构。虽然MCP协议支持，但过于复杂的Schema可能会影响模型理解。一个更实用的做法是创建多个粒度更细、功能更单一的工具，而不是一个巨无霸工具。

场景三：固定参数与动态参数混合有些API需要固定的Header，比如Content-Type: application/json。这可以在Higress的全局或路由级别插件中配置，不一定非要写在MCP描述里。对于每个Tool独有的固定参数，可以在InvokeContext里增加headers或fixedQuery字段来指定。

我的经验是：保持Tool的输入尽可能简单、扁平。如果原有API非常复杂，可以考虑在Higress和后端服务之间，再增加一个轻量的“适配层”（比如一个简单的云函数），将复杂的MCP调用转换为后端API期望的格式，而不是把所有逻辑都塞进MCP配置里。

4.2 权限、安全与监控如何保障？

把内部API暴露给AI，安全是重中之重。

1. 认证与鉴权：

   • MCP Server层面：Higress网关本身支持丰富的认证方式，如JWT、OAuth2、API Key等。你可以在Higress上为/registry路径配置认证，确保只有合法的AI客户端（如公司内部的Cursor部署）可以连接。
   • 后端API层面：原有的API鉴权机制（如Token、AK/SK）依然有效。你可以将鉴权信息像高德Key一样，通过Nacos的加密配置项 (credentialRef) 来管理，由Higress在转发时自动附加。绝对不要将明文密钥写在Tool的描述文件里。

2. 限流与防滥用：

   • AI的调用模式可能和人类不同，可能产生突发流量。务必在Higress网关层为暴露的MCP服务配置限流规则。可以根据Client IP或API Key进行限流，保护后端服务。

3. 监控与可观测性：

   • 日志：确保Higress的访问日志是开启的，并记录下MCP调用的原始请求、转换后的请求、以及后端响应。这对于调试Tool调用失败的问题至关重要。
   • 指标：Prometheus等监控工具可以采集Higress的指标，关注/registry端点的请求量、延迟、错误率。同时，监控后端服务的健康状态和性能。
   • 链路追踪：考虑集成OpenTelemetry，将一次AI对话中可能触发的多个Tool调用串联起来，便于分析整体链路性能和排查问题。

4.3 性能优化与大规模部署建议

当你的Tool数量成百上千时，需要注意性能问题。

• Nacos配置优化：避免单个Data ID的配置过大。可以按业务域或服务拆分多个MCP描述配置文件。Nacos 3.x对配置的推送性能有显著优化，建议升级。
• Higress缓存策略：Higress会缓存从Nacos获取的Tool元数据。理解其缓存更新机制，在频繁更新Tool描述时，可能需要调整缓存TTL或手动触发更新。
• 服务发现粒度：在Higress的serviceMatcher配置中，尽量精确地指定需要关注的服务名，使用正则表达式时也要避免过于宽泛的.*，以减少不必要的网络开销和内存占用。
• 连接管理：MCP over SSE是长连接。确保Higress的SSE连接数限制、超时时间等参数根据你的客户端数量进行合理调整。

5. 未来展望：超越Tool，拥抱更完整的MCP生态

通过Nacos+Higress，我们目前主要解决的是Tool资源的“0改动”暴露问题，这已经覆盖了存量API升级最迫切的需求。但MCP协议不止于此，它还包括Prompt（提示词模板）、Resource（静态资源）等资源类型。

Nacos 3.0的定位正是“AI应用服务管理平台”。我可以预见，未来的演进方向会非常有意思：

• 动态Prompt管理：将反复调试、优化的Prompt模板存储在Nacos中，并关联到特定的Tool或场景。AI客户端可以动态获取最新的Prompt，实现业务逻辑的“热更新”，而无需重新训练或部署模型。
• Tool的智能路由与编排：当Tool数量爆炸时，如何避免给模型一个包含数百个Tool的“冗长列表”？Nacos可以结合标签、场景上下文，向Higress下发“当前对话最可能用到的Top N个Tool”的规则，实现Tool的智能过滤和推荐，节省Token，提升模型表现。
• 与模型服务治理结合：Nacos不仅可以管你的业务API，未来也可以管理模型服务（如OpenAI、通义千问等Endpoint）。实现业务API与模型API在同一个控制面下的统一治理、流量调度和可观测性。

从我实际使用的感受来看，Nacos + Higress 这套组合，最大的价值在于它尊重了现有的技术资产和团队技能。运维同学继续用熟悉的Nacos做配置管理，开发同学无需学习新协议，架构师则快速搭建起了通往AI世界的桥梁。它不是一个颠覆性的重造轮子方案，而是一个优雅的、渐进式的“适配器”方案。在AI浪潮下，这种能快速将现有能力变现为AI能力的工具，无疑具有强大的生命力。如果你正在为存量服务接入AI而发愁，不妨现在就动手试试这套“组合拳”，它可能会给你带来意想不到的惊喜。