实操 SpringBoot+MCP：把本地工具接入 AI 工作流的完整配置

1. 为什么 SpringBoot 项目要接 MCP从 CRUD 到「对话即服务」的落地场景如果你手上有一个跑了很久的 SpringBoot 后端接口一大堆Swagger 文档几十页业务方还是天天在群里问「这个查询怎么调」。这时候 MCPModel Context Protocol就是一个很自然的切入点它把后端已有的能力包装成 AI 客户端能识别的「工具」用户用自然语言说一句「帮我查一下张三写的书」模型自己决定调哪个方法、传什么参数再把结果整理成人话返回。MCP 是什么一句话它是给大模型用的「工具插座协议」。传统做法是每个 AI 应用自己写 function calling 的 JSON Schema模型换一家、客户端换一个就得重写一遍。MCP 把这层抽象出来服务端按协议暴露工具客户端按协议发现和调用双方解耦。对 Java 后端来说最大的好处是你不用改业务逻辑只要在原有 Service 上加注解、注册成工具就能被 Claude Desktop、Cline、Cursor 这类支持 MCP 的客户端直接调用。适合谁三类人最值得动手一是手里有存量 SpringBoot 系统、想低成本加 AI 入口的后端二是做企业内部工具平台、想让非技术同事用自然语言查数据的团队三是想搞明白 MCP 到底怎么跑通、不想只看概念文章的开发者。这篇就按「最小闭环」来写一个图书查询服务从加依赖、写配置、暴露工具到客户端连上、发一次请求、看到数据库真实返回全程可复制。需要提前说清楚的一点MCP 服务端本身不负责「调用大模型」它只负责把工具暴露出去。真正做推理、决定调哪个工具的是客户端背后的大模型。所以你会看到两个角色——MCP Server你的 SpringBoot 应用和 MCP ClientAI 客户端或你自己写的测试端。理解这个分工后面配置就不会绕晕。我试过把公司一个内部订单查询服务按这个思路改造原本要写一份对接文档给 AI 团队改完之后对方直接在客户端里配个地址就能用省掉的沟通成本比写代码本身还多。下面进入实操。2. TaoToken 前置准备拿到 Base URL、API Key 和可用 Model ID在动手改 SpringBoot 之前先把「模型侧」的凭证准备好。因为 MCP 工具调用最终要由大模型来驱动你需要一个能访问模型的入口。这里用 TaoToken 作为统一接入层它提供 OpenAI 兼容的接口Base URL 固定是https://taotoken.net/api你只需要拿一个 API Key再选一个模型 ID 就能跑。第一步打开 https://taotoken.net/api 注册并登录后进入控制台。控制台里能看到「API Keys」菜单点进去创建一个新的 Key。建议按用途命名比如springboot-mcp-demo方便以后区分和吊销。创建后 Key 只显示一次复制下来存到安全的地方别直接提交到 Git。第二步确认你要用的 Model ID。在「模型对话」页面可以看到当前可用的模型列表选一个支持工具调用function calling / tool use的模型这点很关键——不是所有模型都能稳定地按 MCP 协议去调工具。选好后把模型名记下来比如常见的claude-sonnet-4-5这类标识具体以控制台实际展示为准。第三步如果你打算用 Claude Code 或 Cline 这类客户端来连你的 MCP Server还需要在客户端侧配置接入信息。以 Claude Code 为例它的配置文件里需要填三件套Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiKey 填刚才创建的Model ID 填你选的那个。这三样缺一不可很多人连不上就是漏了 Model ID 或者 Base URL 多写了斜杠。注意API Key 属于敏感凭证不要写死在application.yml里提交到仓库。本地开发可以用环境变量比如TAOTOKEN_API_KEY配置里用${TAOTOKEN_API_KEY}引用。生产环境更要用密钥管理服务。如果你只是想先验证 MCP Server 能不能被调用不一定非要接 Claude Desktop可以直接用 TaoToken 的「模型对话」页面配合一个支持 MCP 的客户端做联调或者写个简单的 HTTP 测试端。前置准备到这里就够了一个 Key、一个 Base URL、一个 Model ID。接下来进代码。3. 可复制配置pom.xml 依赖、application.yml 与 MCP Server 注册片段这一节是全文的核心所有片段都可以直接抄。先明确目标把一个已有的BookService暴露成 MCP 工具让客户端能通过 SSE 连上来调用。3.1 pom.xml 依赖与仓库Spring AI 的 MCP 相关依赖目前还在里程碑/快照阶段中央仓库不一定有所以要额外加仓库地址。下面这段直接贴进pom.xmldependencies !-- Spring AI 核心 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId /dependency !-- MCP 服务端WebMVC 版本走 SSE -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webmvc-spring-boot-starter/artifactId /dependency /dependencies repositories repository idspring-milestones/id nameSpring Milestones/name urlhttps://repo.spring.io/milestone/url snapshotsenabledfalse/enabled/snapshots /repository repository idspring-snapshots/id nameSpring Snapshots/name urlhttps://repo.spring.io/snapshot/url releasesenabledfalse/enabled/releases /repository /repositories注意这里只引了服务端 starter没有引客户端。因为我们的 SpringBoot 应用扮演的是 MCP Server 角色客户端是外部的 AI 工具。如果你还想在应用内部自己调模型那才需要额外引模型 starter。3.2 application.yml 配置server: port: 8080 spring: ai: mcp: server: enabled: true name: book-management-server version: 1.0.0 type: SYNC sse-message-endpoint: /mcp/messagetype: SYNC表示同步调用模式适合大多数 CRUD 场景。sse-message-endpoint是客户端发消息的路径SSE 的连接端点通常是/sse两者配合使用。启动后客户端连http://localhost:8080/sse就能发现工具。3.3 用 Tool 注解暴露方法在原有 Service 实现类的方法上加注解不用改方法体Service RequiredArgsConstructor public class BookServiceImpl implements BookService { Resource private BookRepository bookRepository; Override Tool(name findBooksByAuthor, description 根据作者精确查询图书) public ListBook findBooksByAuthor( ToolParam(description 作者姓名) String author) { return bookRepository.findByAuthor(author); } Override Tool(name findBooksByCategory, description 根据图书分类精确查询图书) public ListBook findBooksByCategory( ToolParam(description 图书分类) String category) { return bookRepository.findByCategory(category); } }description写得好不好直接决定模型能不能选对工具。别写「查询图书」这种模糊描述要写清楚「根据作者精确查询」还是「根据书名模糊查询」。3.4 注册 ToolCallbackProvider光有注解还不够要把这些工具注册到 MCP Server 上Configuration public class McpServerConfig { Bean public ToolCallbackProvider bookToolCallbackProvider(BookService bookService) { return MethodToolCallbackProvider.builder() .toolObjects(bookService) .build(); } }到这里MCP Server 侧的配置就齐了。启动应用控制台会打印 MCP Server 初始化的日志看到book-management-server和注册的工具列表就说明成功。4. 验证请求客户端连接参数与一次工具调用的完整返回配置写完不验证等于没写。这一节演示怎么连、怎么发请求、怎么确认工具真的被调用了。4.1 客户端连接参数以支持 MCP 的客户端为例连接一个 SSE 类型的 MCP Server需要填参数值说明传输类型SSE对应服务端的 webmvc starterURLhttp://localhost:8080/sse服务端 SSE 端点消息端点/mcp/message与 yml 中一致名称book-management-server自定义便于识别如果你用的是 Claude Code它的 MCP 配置通常写在settings.json或项目级配置里结构类似{ mcpServers: { book-management-server: { url: http://localhost:8080/sse } } }同时 Claude Code 自身访问模型还需要 Base URL、API Key、Model ID 三件套Base URL 填https://taotoken.net/apiKey 用你在控制台创建的Model ID 用你选的支持工具调用的模型。这三样和 MCP Server 的配置是两回事别混在一起。4.2 发一次真实请求服务端启动后先确认数据库里有测试数据。写一个CommandLineRunner在启动时插入几本书Component RequiredArgsConstructor public class DataInitializer implements CommandLineRunner { Resource private BookRepository bookRepository; Override public void run(String... args) { bookRepository.saveAll(Arrays.asList( new Book(null, Spring实战第6版, 编程, Craig Walls, LocalDate.of(2022, 1, 15), 9787115582247), new Book(null, 深入理解Java虚拟机, 编程, 周志明, LocalDate.of(2019, 12, 1), 9787111641247), new Book(null, 云原生架构, 架构设计, 张三, LocalDate.of(2023, 3, 15), 9781234567890) )); } }然后在客户端里输入「帮我查一下作者是张三的书」。正常流程是客户端把这句话和工具列表一起发给模型模型判断应该调findBooksByAuthor参数author张三客户端通过 MCP 协议把调用转发给你的 SpringBoot 服务服务查库返回客户端再把结果交给模型整理成自然语言。预期返回类似根据查询作者「张三」名下有 1 本图书 - 《云原生架构》架构设计类2023-03-15 出版ISBN 9781234567890如果你在服务端日志里看到findBooksByAuthor被调用、SQL 执行了就说明整条链路通了。这一步是整个最小闭环的关键验证点别跳过。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照实操里最容易卡住的不是代码是各种报错。下面按真实遇到的顺序列。401 Unauthorized。两种可能一是 TaoToken 的 API Key 没填对或过期去控制台重新生成二是 Key 填了但 Base URL 写错比如写成https://taotoken.net/api/多了斜杠或者漏了/api。检查客户端配置里的 Base URL 和 Key 是否匹配。local proxy failed / connection refused。这类报错通常是客户端连不上 MCP Server。先确认 SpringBoot 应用真的起来了curl http://localhost:8080/sse能看到 SSE 流再确认客户端填的 URL 和端口对得上如果服务端和客户端不在同一台机器localhost要换成实际 IP并检查防火墙。reading choices 相关报错。这多半是模型返回结构不符合预期常见于用了不支持工具调用的模型。换一个明确支持 function calling / tool use 的 Model ID 再试。另外检查Tool的description是否为空或过于模糊模型选不出工具时也可能返回异常结构。OAuth / 认证失败。如果你在客户端里配了 OAuth 流程但服务端没实现对应端点就会报这个。MCP Server 本身不强制 OAuth本地开发直接用 SSE 无认证即可。生产环境要加认证的话建议在 Spring Security 层做而不是指望 MCP 协议自带。工具列表为空。客户端连上了但看不到工具检查McpServerConfig里的ToolCallbackProviderBean 是否被扫描到Tool注解的类是否是 Spring Bean。常见坑是把工具方法写在没被Service或Component标注的类里。Codex auth.json 相关。如果你用 Codex 类客户端认证信息在auth.json里格式错了会直接启动失败。确认里面的 Base URL、Key、Model ID 三件套齐全JSON 语法正确别有多余逗号。排查顺序建议先看服务端日志有没有收到请求再看客户端日志有没有发出请求最后看模型侧返回。三段日志一对问题基本定位。6. 把 MCP 接进长期工作流Coding Plan 与后续演进跑通最小闭环之后下一步就是把它用起来。如果你只是偶尔查一下数据手动启动服务、手动连客户端就够了。但如果你想让 AI 长期帮你处理编码任务、自动调内部工具那就需要一个稳定的接入方案。TaoToken 的 Coding Plan 适合这种长期编码和 Agent 场景它把模型调用和工具链的额度统一管理不用每次手动换 Key。对于团队来说把 MCP Server 部署到内网客户端统一走 Coding Plan 接入既省事又好审计。具体操作上你可以把 MCP Server 打成 jar 部署到测试环境客户端配置里把 URL 换成测试环境地址。然后去 https://taotoken.net/api 的「接入文档」页面确认最新的连接参数格式因为协议和客户端配置偶尔会更新以文档为准最稳。想先验证模型能力可以去「模型对话」页面直接试要管理 Key 就去「API Keys」长期编码任务则看「Coding Plan」。最后给一个实用建议MCP 工具的description要当成产品文案来写。模型选工具全靠它写得清楚调用准确率能差出一大截。我踩过的坑就是一开始描述太简略模型老是调错方法把描述补详细之后基本一次就对。这个细节比任何配置技巧都值钱。