1. 存量 Spring Boot 服务接入 MCP 的真实痛点如果你手上有一套跑了很久的 Spring Boot 服务接口稳定、调用方固定突然有一天产品说“让 AI 也能调这些接口”你第一反应大概率是难道要把每个 Controller 都重写一遍我试过直接引 Spring AI 的 MCP Server 依赖结果发现存量项目里spring-boot-starter-web的版本、Jackson 的序列化策略、甚至全局异常处理器都会跟新依赖打架改完一圈业务代码回归测试的成本比新写一个服务还高。这就是存量服务改造 MCP 的核心矛盾MCP 本身是个好东西它把“AI 调用外部工具”这件事标准化了模型只要拿到工具列表和参数 schema就能自己决定调哪个接口、传什么参数。但标准化的代价是你得让服务“说 MCP 的话”。对于新项目加个依赖、写几个注解就完事对于存量项目任何代码侵入都意味着耦合度上升和回归风险。所以更优雅的思路是“加一层”而不是“改一层”。具体来说让存量 Spring Boot 服务保持原样继续用 REST API 对外提供服务然后通过 Nacos 做服务注册发现再让 Higress 网关把 REST 接口动态转换成 MCP 协议暴露出去。整个链路里业务代码一行不动改造全部发生在配置层。这套方案适合谁适合手里有存量 REST API、想快速接入 AI Agent 生态的后端团队适合已经在用 Nacos 做微服务治理、想复用现有注册中心的架构也适合想验证 MCP 调用效果、但不想动生产代码的开发者。下面我把完整路径拆开从环境准备到客户端验证每一步都给可复制的配置。2. TaoToken 前置准备模型调用与 MCP 验证的入口在动手改造之前有一个前置问题需要解决MCP 服务改造完之后你总得有个支持 MCP 协议的客户端来验证工具列表和调用结果。Cursor、Cherry Studio 这类工具可以但它们背后仍然需要一个能稳定调用模型的 API 入口。我实测下来用 TaoToken 作为模型调用层比较省心它兼容 OpenAI 风格的接口配置简单适合在验证阶段快速跑通链路。TaoToken 在这里扮演的角色是“模型能力的统一入口”。你的 MCP 客户端负责发现工具、组装参数、发起调用而模型负责理解用户意图、决定调哪个工具。两者配合才能完成一次完整的 MCP 调用。所以你需要先拿到一个可用的 API Key并确认模型 ID。具体操作路径访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时建议给 Key 起一个能区分用途的名字比如mcp-verify方便后续排查。拿到 Key 之后你需要确认两件事Base URL 和 Model ID。Base URL 用 https://taotoken.net/api 注意这个地址不带 UTM 参数直接作为 API 请求前缀。Model ID 根据你实际要用的模型填写比如claude-sonnet-4-20250514或gpt-4o这类。如果你不确定当前账号支持哪些模型可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 先手动聊一句确认模型可用。这里有个容易踩的坑很多人把 Base URL 写成带/v1的地址结果客户端拼接后变成/v1/v1/chat/completions直接 404。TaoToken 的 API 地址是 https://taotoken.net/api 客户端一般会自动补/v1所以你在配置里填根地址就行。如果你用的是 Claude Code 这类工具接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同客户端的完整配置示例。另外如果你后续要做长期编码或 Agent 类任务可以关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用场景。验证阶段先用普通 API Key 就够了。把 Key、Base URL、Model ID 这三样准备好后面在 MCP 客户端里配置时直接填进去。这一步看起来简单但实际排障时80% 的“模型不响应”问题都出在这三个参数上所以建议先单独用 curl 测一下模型接口通不通再往下走。3. 可复制配置Nacos 注册、Higress 路由与 MCP 声明这一节是整篇的核心所有配置都可以直接复制。我按“服务注册 → MCP 声明 → 协议转换 → 网关路由”的顺序拆开每一步都说明改哪个文件、填什么值。先看存量 Spring Boot 服务注册到 Nacos。假设你的服务叫book-service端口 8090Nacos 地址是localhost:8848。在application.yml里加server: port: 8090 spring: application: name: book-service cloud: nacos: discovery: server-addr: localhost:8848 username: nacos password: nacos对应的 Maven 依赖需要spring-cloud-starter-alibaba-nacos-discovery版本跟 Spring Cloud Alibaba 对齐。启动后Nacos 控制台“服务管理 → 服务列表”里能看到book-service说明注册成功。接下来在 Nacos 控制台创建 MCP Server。进入“MCP 管理 → MCP 列表”点“创建 MCP Server”填写MCP 服务名book-mcp协议类型选sse转 MCP 服务选http后端服务选“使用已有服务”服务引用选book-service版本1.0.0。发布后再点编辑把版本改成1.1.0此时下方 Tools 区域会出现“添加”按钮。为每个 REST 接口添加 Tool。以“根据作者查询图书”为例Tool 名称getBooksByAuthor描述“根据作者姓名查询图书列表”输入参数添加authorName。协议转换配置填{ requestTemplate: { url: /books/author, argsToUrlParam: true, method: GET }, responseTemplate: { body: {{ .body | raw }} }, argsPosition: { authorName: query } }这段 JSON 的含义url是后端接口路径argsToUrlParam: true会把argsPosition里标记为query的参数拼成?authorNamexxxmethod必须跟GetMapping一致。responseTemplate里的{{ .body | raw }}保证返回的 JSON 不被转义。按同样方式给/books/category和/books/all各建一个 Tool注意/books/all没有参数argsPosition留空即可。然后配置 Higress 的协议转换。进入 Higress 数据目录找到higress-config.yaml确认 MCP 相关开关已启用。保存后执行docker restart higress-ai重启容器。最后在 Higress 控制台“服务来源 → 创建服务来源”类型选 Nacos地址填localhost:8848命名空间和分组按实际填确定后 Higress 就能发现book-service。如果你用的是 Cline MCP 或 Claude Code 这类客户端配置里需要写全三件套Base URL、Key、Model ID。以 Cline 的 MCP 配置为例{ mcpServers: { book-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse } } }注意这里的8001是 Higress 控制台端口/mcp/book-mcp/sse是 Nacos 里定义的 MCP 服务名拼出来的路径。如果你的 Higress 网关端口不同按实际改。模型侧仍然用 TaoToken 的 Base URL 和 Key两者是独立的MCP 负责工具发现TaoToken 负责模型推理。4. 验证请求用 MCP 客户端调用工具列表与结果配置完成后验证分两步先确认工具列表能被发现再确认调用结果正确。第一步用 curl 直接请求 MCP 的 SSE 端点看工具列表是否返回。命令如下curl -N http://127.0.0.1:8001/mcp/book-mcp/sse如果返回里包含getBooksByAuthor、getBooksByCategory、getAllBooks三个工具名和对应的参数 schema说明 MCP 声明生效了。如果返回空或报错先检查 Higress 是否重启成功、Nacos 服务来源是否连上。第二步在支持 MCP 的客户端里实际调用。以 Cursor 为例打开设置里的 MCP 配置添加book-mcp的 SSE 地址。保存后在对话里输入“帮我查一下 Tolkien 写的书”模型会先列出可用工具然后选择getBooksByAuthor传入authorName: Tolkien。后端日志会打印Received request to find books by author: Tolkien客户端返回 Tolkien 的两本书。这里有个细节responseTemplate里的{{ .body | raw }}必须写对否则返回的 JSON 会被二次转义模型解析时可能报reading choices之类的错误。如果你看到返回内容里出现\这种转义字符就是这里配错了。再测一个无参数接口输入“列出所有图书”模型应该调用getAllBooks返回 5 本书的完整列表。如果模型没有调用工具而是直接编造答案说明工具描述不够清晰或者模型没有正确加载工具列表。这时候回到 Nacos 检查 Tool 描述是否写清楚描述里最好包含“查询”“列表”这类动词。验证通过后你可以把同样的配置复制到其他存量服务上。只要服务注册到 NacosMCP 声明和 Higress 路由的配置结构完全一致改的只是服务名和接口路径。5. 本篇常见错排查401、local proxy failed 与 reading choices改造过程中最容易卡住的几个报错我按实际遇到的频率排一下。第一个是401 Unauthorized。这个通常不是 MCP 的问题而是模型侧 Key 配错了。检查 TaoToken 的 API Key 是否填在正确的位置Base URL 是否是 https://taotoken.net/api 有没有多写/v1。如果你用的是 Claude Code检查auth.json里的配置确保 Key 和 Base URL 对应。另外Nacos 如果开了鉴权username和password也要填对否则服务注册不上后续 MCP 声明会找不到后端服务。第二个是local proxy failed。这个报错一般出现在 Higress 转发阶段说明网关没能把请求转到后端服务。排查顺序先确认book-service在 Nacos 里是健康状态再确认 Higress 的服务来源里能看到这个服务最后检查higress-config.yaml里的 MCP 开关是否启用、容器是否重启。如果 Higress 和 Nacos 不在同一台机器server-addr要填实际 IP不能写localhost。第三个是reading choices或类似的 JSON 解析错误。这个多半是responseTemplate配置问题。{{ .body | raw }}必须原样写不能改成{{ .body }}否则返回的 JSON 会被当成字符串处理模型拿到的是转义后的内容解析时就会报错。另外如果后端接口返回的不是标准 JSON比如返回了 HTML 错误页也会导致这个报错先用 curl 直接调后端接口确认返回格式。第四个是 OAuth 相关报错。如果你在 MCP 客户端里看到 OAuth 认证失败检查客户端是否要求 OAuth 流程而你的 MCP 服务是 SSE 直连。大部分本地验证场景不需要 OAuth直接在客户端配置 URL 即可。如果客户端强制 OAuth换一个支持 SSE 直连的客户端比如 Cursor 或 Cherry Studio。排障时建议按“模型侧 → 网关侧 → 服务侧”的顺序查先用 curl 测 TaoToken 的模型接口确认 Key 和 Base URL 没问题再测 Higress 的 SSE 端点确认工具列表能返回最后看后端服务日志确认请求真的到了业务代码。这样能快速定位是哪一层出的问题。6. 语义一致 CTA从验证到长期编码的路径链路跑通之后你可能会想把这套方案用到更多存量服务上或者接入更复杂的 Agent 场景。这时候有几个入口可以按需使用。如果你还在验证阶段需要反复测试模型和 MCP 工具的配合可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试。它适合单次验证不用配客户端就能看模型是否能正确选择工具。如果你要长期做编码类任务或者构建需要频繁调用工具的 AgentCoding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适它在高频调用场景下更稳定。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Claude Code、Cline 等客户端的完整配置示例包括 Base URL、Key、Model ID 三件套的填法。如果你需要管理多个 Key 或查看调用量API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以创建和吊销 Key。控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 则能看到整体用量和账单。最后说一个实际经验存量服务改 MCP最大的收益不是“让 AI 能调接口”而是“让接口的调用方从人变成 Agent”。这意味着你的接口描述、参数命名、返回结构都要开始考虑模型能不能理解。比如authorName比name更清晰getBooksByAuthor比query更明确。这些细节在人工调用时无所谓但在 MCP 场景下直接影响模型的选择准确率。所以改造完成后回头优化一下 Tool 描述和参数命名比多接几个服务更有价值。