1. 存量 REST API 转 MCP 的真实痛点与场景拆解手里有一套跑了很久的 Spring Boot 图书服务接口稳定、日志清晰、监控齐全但每次想让 AI Agent 调用它就得写一堆胶水代码要么在 Agent 侧硬编码 HTTP 请求要么单独写一个 Function Calling 的适配层。接口一多参数映射、鉴权、错误处理全散落在各个地方改一个字段要动三四个文件。MCPModel Context Protocol出现之后思路变了把存量 RESTful API 直接声明成 MCP Server让 AI Agent 通过标准协议发现工具、调用工具。问题在于存量服务不会为了 MCP 重写一遍我们需要一个中间层来完成「HTTP 接口 → MCP Tool」的协议转换。这就是 Nacos3 Higress 组合的用武之地。Nacos3 负责服务注册与发现把已有的 book-service 注册进去Higress 作为 AI 网关从 Nacos 拉取服务列表把具体的 REST 接口映射成 MCP Tools对外暴露 SSE 或 streamableHTTP 端点。整个链路里存量代码几乎不用改只需要在 Nacos 控制台声明 MCP 服务、在 Higress 里配置协议转换模板。适合谁看手上有一批 RESTful 接口、想让 AI Agent 直接调用的后端同学正在做企业内部工具链 AI 化、又不想大改存量系统的架构同学以及想搞清楚 MCP 协议转换到底怎么落地、不想只看概念的同学。这篇会从 Nacos3 安装配置开始到 Higress 部署、Redis 挂载、MCP 服务声明、Tool 映射、协议转换 JSON 配置最后用 curl 验证工具列表和调用链路。每一步都给可复制的配置片段踩过的坑也会标出来。核心检索词先明确Nacos3 服务发现、Higress MCP 网关、存量 API 转 MCP Server、TaoToken 统一 Key 通道。这四个词贯穿全文后面每个环节都会对应到具体操作。2. TaoToken 统一 Key 通道的前置准备与接入定位在讲 Nacos 和 Higress 的具体配置之前先把 TaoToken 的角色说清楚。很多同学会问MCP Server 都搭好了为什么还要接 TaoToken原因在于鉴权和调用入口的统一。存量 API 转成 MCP 之后调用方可能是 Cursor、Cherry Studio、Cline也可能是你自己写的 Agent。每个客户端的 Key 管理方式不一样有的走 Header有的走 Query有的走 OAuth。如果每个 MCP Server 都单独配一套鉴权维护成本会迅速膨胀。TaoToken 在这里承担的是统一 Key 通道的角色所有 MCP 调用走同一个 Base URL用同一套 API Key模型侧和工具侧共用一套凭证体系。你不需要在每个 MCP Server 里重复配置鉴权逻辑只需要在 TaoToken 侧管理 Key在 Higress 侧做转发。前置准备分三块第一块是 TaoToken 侧的 Key。访问 https://taotoken.net/api-keys 创建 API Key这个 Key 后面会用在 MCP 客户端的配置里。注意 Key 只在创建时显示一次复制后妥善保存。第二块是模型侧的准备。如果你打算让 Agent 在调用 MCP 工具的同时还能做推理需要确认模型通道可用。可以到 https://taotoken.net/models 看一下当前支持的模型列表选一个适合工具调用的模型。工具调用对模型的 Function Calling 能力有要求不是所有模型都支持。第三块是文档侧的准备。MCP 接入的完整参数说明在 https://taotoken.net/doc建议先过一遍特别是 Base URL 的格式和 Header 的写法。很多 401 报错都是因为 Base URL 多写了斜杠或者少写了版本路径。这里给一个最小可用的 MCP 客户端配置片段后面验证阶段会用到{ mcpServers: { book-service-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } } }注意 url 里的路径结构/mcp/{MCP服务名}/sseMCP 服务名是你在 Nacos 里声明时填的那个。headers 里的 Authorization 是 TaoToken 的 Key格式是Bearer加 Key 本身。如果你用的是 Cline 或者 Claude Code 这类支持 MCP 的编码工具配置方式类似但字段名可能不同。Cline 的 MCP 配置在 settings 里Claude Code 的配置在~/.claude/settings.json或者项目级的.mcp.json。不管哪个客户端三件套不能少Base URL、Key、Model ID。Base URL 指向 TaoToken 的 API 地址Key 用刚才创建的Model ID 选一个支持工具调用的。TaoToken 的 Coding Plan 适合长期编码场景如果你打算把 MCP 工具链用在日常开发里可以到 https://taotoken.net/coding-plan 看一下套餐说明。模型对话调试入口在 https://taotoken.net/chat验证模型连通性的时候可以用。前置准备做完接下来进入 Nacos3 的安装和配置。3. Nacos3 安装配置与 Higress 网关部署的可复制片段3.1 Nacos3 安装与 application.properties 配置Nacos3 的安装比 Nacos2 多了一个 AI MCP Registry 的端口配置这是它原生支持 MCP 服务注册的关键。下载解压后修改conf/application.properties下面是我实测可用的配置片段nacos.server.main.port8848 spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos?useUnicodetruecharacterEncodingUTF-8autoReconnecttrue db.user.0root db.password.0123456 nacos.config.push.maxRetryTime50 nacos.naming.empty-service.auto-cleantrue nacos.naming.empty-service.clean.initial-delay-ms50000 nacos.naming.empty-service.clean.period-time-ms30000 nacos.ai.mcp.registry.port9080 nacos.server.contextPath/nacos nacos.console.port8090 nacos.console.contextPath nacos.console.remote.server.context-path/nacos nacos.core.auth.system.typenacos nacos.core.auth.enabledfalse nacos.core.auth.admin.enabledfalse nacos.core.auth.plugin.nacos.token.enabledfalse nacos.core.auth.console.enabledfalse nacos.core.auth.caching.enabledfalse nacos.core.auth.server.identity.key123 nacos.core.auth.server.identity.value123 nacos.core.auth.plugin.nacos.token.cache.enablefalse nacos.core.auth.plugin.nacos.token.expire.seconds18000 nacos.core.auth.plugin.nacos.token.secret.keyVGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg nacos.core.api.compatibility.console.enabledtrue nacos.istio.mcp.server.enabledtrue nacos.k8s.sync.enabledfalse nacos.deployment.typemerged几个关键点说明。nacos.ai.mcp.registry.port9080是 MCP 注册端口Higress 会通过这个端口拉取 MCP 服务列表。nacos.console.port8090是控制台端口默认是 8848这里改成 8090 是为了避免和主端口冲突。nacos.core.auth.enabledfalse在本地开发环境可以关掉鉴权生产环境记得打开并配置好 token secret key。MySQL 地址要改成你自己的。如果本地没有 MySQL可以用 Docker 快速起一个docker run -d --name nacos-mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD123456 \ -e MYSQL_DATABASEnacos \ mysql:8.0启动 Nacos 后访问http://127.0.0.1:8090/确认控制台正常。如果页面打不开先看日志里有没有数据库连接失败的报错。3.2 Higress 与 Redis 的 Docker 部署Higress 我用的是 all-in-one 镜像在 WSL2 的 Docker Desktop 里跑。先创建一个数据目录然后执行docker run -d --name higress-ai \ -v C:\software\higress\higressData:/data \ -p 8001:8001 -p 8081:8080 -p 8443:8443 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest端口映射说明8001 是 Higress 控制台端口8081 映射到容器内的 8080 是网关数据面端口8443 是 HTTPS 端口。访问http://127.0.0.1:8001/进入控制台第一次登录会初始化账号密码。Redis 是 Higress 做 MCP 会话管理必需的不装的话 MCP 的 SSE 连接会断。执行docker run -d --name higress-redis \ -p 6379:6379 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/redis-stack-server:7.4.0-v3装完之后在 Higress 控制台里配置 Redis 连接信息地址填host.docker.internal:6379或者你宿主机的 IP。配置完记得重启 Higress 容器否则不生效。3.3 Higress 接入 Nacos 与 MCP 开关在 Higress 控制台的「服务来源」里添加 Nacos地址填host.docker.internal:8848命名空间用 public。然后在「AI 网关」里开启 MCP Server 功能选择 Redis 作为会话存储。这一步的配置会生成一段 JSON类似{ mcpServerEnabled: true, redisConfig: { host: host.docker.internal, port: 6379, db: 0 }, nacosConfig: { serverAddr: host.docker.internal:8848, namespace: public } }配置保存后重启容器Higress 就能从 Nacos 拉取服务列表了。4. 存量 API 声明为 MCP Tool 的协议转换配置与验证4.1 服务注册到 Nacos3先准备一个简单的 Spring Boot 图书服务注册到 Nacos。pom.xml 关键依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependencyapplication.ymlserver: port: 8090 spring: application: name: book-service cloud: nacos: discovery: server-addr: localhost:8848 username: nacos password: nacosController 里定义三个接口按作者查、按分类查、查全部。启动后到 Nacos 控制台的服务列表里确认book-service已经注册上来。4.2 在 Nacos 声明 MCP 服务在 Nacos 控制台的「MCP 管理」里新建 MCP 服务。关键字段MCP 服务名填book-mcp协议类型选sse转 MCP 服务选http后端服务选「使用已有服务」服务引用选book-service描述填「图书查询服务」版本填1.0.0。填完点发布。4.3 将 REST API 映射为 MCP Tools在 MCP 列表里找到book-mcp点编辑添加 Tool。以「根据作者查询图书」为例Tool 名称填getBooksByAuthor描述填「根据作者姓名查询图书列表」输入参数添加authorName类型 string。协议转换配置填{ requestTemplate: { url: /books/author, argsToUrlParam: true, method: GET }, responseTemplate: { body: {{ .body | raw }} }, argsPosition: { authorName: query } }这段配置的含义requestTemplate.url指定后端路径argsToUrlParam为 true 时把 query 参数拼到 URL 上method是 GET。responseTemplate.body用{{ .body | raw }}保留原始 JSON 格式。argsPosition声明authorName放在 query 里。按同样方式配置另外两个 ToolgetBooksByCategory对应/books/category参数categorygetAllBooks对应/books/all无参数。配置完点发布。4.4 用 curl 验证 MCP 工具列表与调用链路MCP 服务发布后先验证工具列表。SSE 端点需要先建立连接拿 session再用 session 发请求。简化验证可以用 streamableHTTP 端点curl -X POST http://127.0.0.1:8001/mcp/book-mcp/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }正常返回会列出三个 Tool 的定义包含 name、description、inputSchema。如果返回 401检查 Authorization 头如果返回 404检查 MCP 服务名和路径。调用工具curl -X POST http://127.0.0.1:8001/mcp/book-mcp/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: getBooksByAuthor, arguments: { authorName: Tolkien } } }预期返回包含两本书的 JSON 数组。如果返回空数组检查后端服务的参数名是否匹配authorName要和 Controller 里的RequestParam(authorName)一致。在 Cherry Studio 或 Cursor 里配置 MCP Serverurl 填http://127.0.0.1:8001/mcp/book-mcp/sseheaders 加 TaoToken 的 Key。连接成功后在对话里问「帮我查一下 Tolkien 写的书」Agent 会自动调用getBooksByAuthor工具并返回结果。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见的报错。原因通常是三个Key 没传、Key 格式不对、Key 过期。检查 Header 里是不是Authorization: Bearer sk-xxx注意 Bearer 后面有一个空格。如果用的是 TaoToken 的 Key确认 Key 没有多余的空格或换行。到 https://taotoken.net/api-keys 重新生成一个 Key 试试。还有一种情况是 Higress 侧的鉴权插件和 TaoToken 的 Key 冲突。如果 Higress 开了 JWT 鉴权需要把 MCP 路径加到白名单里让 TaoToken 的 Key 透传到后端。5.2 local proxy failed这个报错通常出现在 Higress 转发到 Nacos 服务的时候。原因可能是 Nacos 服务实例的 IP 是容器内 IPHigress 容器访问不到。解决办法在 Nacos 服务注册时指定宿主机 IP或者在 Higress 的 Nacos 配置里把serverAddr改成宿主机可达的地址。WSL2 环境下host.docker.internal通常能解析到宿主机但 Nacos 注册的服务 IP 如果是172.x.x.x的容器 IPHigress 就访问不到。检查方式在 Higress 容器里curl http://book-service-ip:8090/books/all看能不能通。不通的话在 Spring Boot 配置里加spring.cloud.nacos.discovery.ip宿主机IP。5.3 reading choices 报错这个报错一般出现在模型侧不是 MCP 侧。原因是模型返回的 tool_calls 格式不完整或者 MCP 返回的结果格式不符合模型预期。检查 MCP Tool 的responseTemplate.body是不是{{ .body | raw }}如果写成{{ .body }}可能会被转义导致 JSON 解析失败。另外确认模型支持 Function Calling不支持的话换一个模型。5.4 OAuth 相关报错如果 MCP 客户端配置里带了 OAuth 相关字段但 TaoToken 的 Key 是 Bearer 模式会报 OAuth 校验失败。把 OAuth 配置去掉只用 Authorization Header。Claude Code 的配置里如果出现oauth字段删掉改成{ mcpServers: { book-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } } }Codex 的auth.json里如果配了 OAuth也要改成 API Key 模式。三件套确认Base URL 指向 TaoToken 的 API 地址Key 用 Bearer 格式Model ID 选支持工具调用的。5.5 MCP 服务列表为空Higress 控制台里看不到 Nacos 注册的 MCP 服务。检查 Nacos 的nacos.ai.mcp.registry.port9080是否配置Higress 的 Nacos 地址是否指向正确的端口。另外确认 Nacos 的 MCP 服务已经发布草稿状态不会同步到 Higress。6. 从验证到长期使用TaoToken 通道下的 MCP 调用建议MCP 工具链跑通之后日常使用有几个点值得注意。第一Key 的轮换。TaoToken 的 Key 支持多创建几个不同客户端用不同的 Key方便排查问题。如果某个 Key 泄露单独吊销不影响其他客户端。第二MCP 服务的版本管理。Nacos 里声明 MCP 服务时填的版本号建议和存量 API 的版本对齐。接口有变更时新建一个 MCP 服务版本而不是直接改旧的避免正在使用的 Agent 突然调不到工具。第三调用日志。Higress 的访问日志里能看到每次 MCP 调用的请求和响应排查问题时很有用。日志默认在容器内的/var/log/higress/下可以挂载出来。第四模型选择。工具调用对模型的 Function Calling 能力有要求实测下来支持工具调用的模型在参数提取和结果整合上差异明显。可以到 https://taotoken.net/models 对比一下选一个适合自己场景的。第五长期编码场景。如果你打算把 MCP 工具链用在日常编码里比如让 Agent 查内部文档、查数据库、调内部 APITaoToken 的 Coding Plan 在成本和稳定性上更适合长期使用。入口在 https://taotoken.net/coding-plan。最后给一个完整的 MCP 客户端配置模板把 Base URL、Key、Model ID 三件套都带上{ mcpServers: { book-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } }, model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelId: claude-sonnet-4-20250514 } }这套配置在 Cursor、Cline、Cherry Studio 里都能用字段名可能略有差异但核心三件套不变。MCP 接入文档在 https://taotoken.net/doc遇到配置问题可以先查文档。整个链路跑通之后存量 API 不用改一行代码就能被 AI Agent 通过标准 MCP 协议调用。Nacos3 负责服务发现Higress 负责协议转换TaoToken 负责统一鉴权和调用入口。这套组合在内部工具链 AI 化的场景里落地成本比想象中低很多。