MCP 架构设计案例剖析：Nacos MCP Registry 实现存量应用接口升级 MCP 协议

1. 存量 HTTP 接口升级 MCP 的真实痛点如果你手里有一套跑了很久的 Spring Cloud 或 Dubbo 服务接口稳定、注册在 Nacos 上现在老板说“我们要接大模型 Agent把这些接口变成 MCP Tool 让模型能调”你第一反应大概率是难道要把每个 Controller 都重写一遍MCPModel Context Protocol是 Anthropic 提出的标准化协议让 Agent 应用能以统一方式发现和调用下游工具。它解决的是“模型怎么知道有哪些工具、每个工具要传什么参数、调用结果怎么回传”这一整套上下文问题。适合谁适合已经有云原生存量服务、又不想大动干戈的团队。传统做法是给每个接口手写一个 MCP Server用 Python 或 TypeScript 把 HTTP 调用包一层。接口少还行接口一多改造成本和时间成本直接劝退。Nacos MCP Registry 的思路不一样它把 Nacos 当控制面管理 Tool 的元信息把 Higress AI 网关当数据面负责 MCP 协议和 HTTP 协议之间的转换。存量服务只需要补一份接口描述代码零改动。这篇就按“注册、发现、协议转换”三层架构拆开讲给出可复制的 Nacos 配置片段、MCP Registry 注册参数、接口映射示例最后用 MCP 客户端把整条工具调用链路验证一遍。我试过在本地把一套订单查询接口挂上去整个过程没动一行业务代码。2. 三层架构拆解注册、发现、协议转换2.1 注册层Nacos 存的是什么普通服务调用里Consumer 知道 Provider 的地址按约定参数调用。大模型要调用缺的是“接口集合 参数描述”这份上下文。Nacos 引入“应用全局描述”概念把应用和接口的详细信息存下来。注册层要落三样东西服务地址Nacos 里本来就有、Tool 元信息名称、描述、参数 schema、接口映射规则MCP Tool 参数怎么映射到 HTTP 请求的 path、query、body。这些信息通过 Nacos 的配置管理能力持久化支持历史版本、灰度、加密。2.2 发现层Tool 列表怎么暴露MCP Client 启动时会调tool/list拿工具清单。这一步由 Higress 的 MCP Server 插件完成它从 Nacos 读取当前应用下所有 Tool 的描述转成标准 MCP 协议的tool/list返回结果。返回里包含每个 Tool 的作用描述和参数描述类型、是否必填、含义模型据此判断该不该调、怎么调。2.3 协议转换层JSON-RPC 怎么变 HTTP当模型决定调用某个 ToolMCP Client 发的是tool/call的 JSON-RPC 请求。Higress 解析这个请求根据你在 Nacos 里配的参数映射信息、Path、后端地址生成对应的 HTTP 请求转发给存量服务。服务返回后Higress 再把结果包装成标准tool/call响应回给 Client。整个链路里Nacos 是控制面Higress 是数据面存量服务只提供接口描述不碰协议转换逻辑。这就是“零改造”的实质。3. 前置准备Nacos 与 Higress 环境动手前确认几件事。Nacos 需要 2.4.x 及以上版本MCP Registry 能力在这个版本线提供。Higress 需要开启 MCP Server 插件并且和 Nacos 打通服务发现。先看 Nacos 侧的基础配置。在application.properties里确认持久化服务发现开启# Nacos 服务端配置片段 nacos.core.auth.enabledtrue nacos.core.auth.plugin.nacos.token.secret.key你的密钥 nacos.naming.clean.empty-service.interval60000Higress 侧需要在插件配置里指向 Nacos 地址并声明 MCP Server 的 SSE 端点。下面是一段网关插件配置示例# Higress mcp-server 插件配置 mcpServer: enabled: true ssePath: /mcp/sse messagePath: /mcp/message registry: type: nacos serverAddr: 127.0.0.1:8848 namespace: public group: DEFAULT_GROUP配好后重启网关访问http://网关地址/mcp/sse应该能建立 SSE 连接。这一步通了说明发现层和协议转换层的基础链路是活的。4. 可复制配置Tool 注册与接口映射4.1 应用全局描述配置在 Nacos 配置中心新建一个配置Data ID 用应用名-mcp-tools.jsonGroup 用MCP_TOOLS。内容是一份 Tool 描述清单{ appName: order-service, baseUrl: http://order-service.default.svc.cluster.local:8080, tools: [ { name: queryOrder, description: 根据订单号查询订单详情返回状态、金额、下单时间, method: GET, path: /api/order/{orderId}, parameters: { type: object, properties: { orderId: { type: string, description: 订单号例如 ORD20240101001 } }, required: [orderId] }, paramMapping: { orderId: path } } ] }这里paramMapping是关键它告诉 HigressMCP 传来的orderId参数要填到 HTTP 请求的 path 里。如果参数要放 query 或 body把值改成query或body即可。4.2 带 Body 的 POST 接口映射再补一个创建订单的 Tool演示 body 映射{ name: createOrder, description: 创建新订单需要商品ID和数量, method: POST, path: /api/order, parameters: { type: object, properties: { productId: { type: string, description: 商品ID }, quantity: { type: integer, description: 购买数量 } }, required: [productId, quantity] }, paramMapping: { productId: body, quantity: body } }paramMapping里标body的参数会被组装成 JSON body 发给后端。标query的会拼到 URL 上。这样一套映射规则覆盖了 GET、POST 的常见场景。4.3 发布与生效配置发布后Nacos 会推送变更到 Higress。你可以在 Nacos 控制台看到配置的历史版本出问题能一键回滚。灰度场景下可以按 IP 或标签分批推送先让一部分 MCP Client 用上新 Tool 描述观察效果再全量。5. 验证请求用 MCP 客户端跑通调用链路配置就绪后用 MCP 客户端验证。这里用官方 Python SDK 写一个最小客户端import asyncio from mcp import ClientSession from mcp.client.sse import sse_client async def main(): async with sse_client(http://网关地址/mcp/sse) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools.tools]) result await session.call_tool( queryOrder, arguments{orderId: ORD20240101001} ) print(调用结果:, result.content) asyncio.run(main())运行后第一步list_tools应该返回你在 Nacos 里配的queryOrder和createOrder。第二步call_tool会触发 Higress 把 JSON-RPC 转成 HTTP GET 请求打到order-service再把响应包回来。如果结果里能看到订单详情说明注册、发现、协议转换三层全部打通。整个过程业务代码一行没改只加了一份 JSON 配置。6. 本篇常见错排查Tool 列表为空先确认 Nacos 配置的 Group 和 Higress 插件里配的 Group 一致。再检查 Data ID 是否匹配应用名-mcp-tools.json这个约定。配置没发布或发布到了错误命名空间都会导致列表为空。调用返回 404多半是path或baseUrl拼错了。注意path里的占位符{orderId}要和paramMapping里的 key 完全对应大小写敏感。baseUrl 不要带结尾斜杠否则可能拼出双斜杠。参数没传进去检查paramMapping的值是不是path、query、body三者之一。写成别的字符串Higress 会忽略这个参数。body 类型参数要确保后端接口的 Content-Type 是application/json。SSE 连接建立后立刻断开通常是网关的 SSE 超时配置太短。把 Higress 的sseTimeout调大或者检查中间有没有负载均衡器提前掐断长连接。改了配置不生效Nacos 推送有延迟等几秒再试。如果还不生效看 Higress 日志里有没有收到 Nacos 的配置变更事件。插件版本过旧也可能不支持动态刷新升级到最新版。7. 接入与验证入口把存量接口升级成 MCP Tool 之后下一步就是让模型真正用起来。如果你要验证模型对 Tool 的调用效果可以直接在模型对话里挂上这个 MCP Server 试跑观察模型选工具、填参数的准确度。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果你是要长期做编码类 Agent、把 MCP 工具链接进日常开发流Coding Plan 更适合入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入过程中需要生成和管理 API Key去控制台的 API Keys 页面操作https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。协议转换和注册参数的细节接入文档里有完整字段说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后提醒一个实际踩过的坑Tool 描述写得太模糊模型会乱调。description里把“什么时候该用这个工具”写清楚比堆参数类型更有用。Nacos 支持动态改描述并实时生效调优时不用重启任何服务。