SpringAI开发MCP-Server（一）：0-1的搭建与实现

1. 为什么 Java 开发者需要一个 MCP-Server如果你正在用 Spring Boot 写业务系统手里已经有一堆 Service、JdbcTemplate、Feign 客户端现在想让大模型直接调用这些能力最直接的路子就是搭一个 MCP-Server。MCP 全称 Model Context Protocol你可以把它理解成模型和外部系统之间的“标准插座”模型不关心你内部是 Doris、MySQL 还是某个 HTTP 接口它只按协议发请求MCP-Server 负责把请求翻译成业务代码能懂的操作再把结果按协议返回。SpringAI 从 1.0.0 开始提供了spring-ai-starter-mcp-server-webmvc它做的事情很纯粹——把普通 Spring Bean 上带Tool注解的方法自动注册成模型可调用的工具同时用 WebMVC 承载 HTTP/SSE 通信。也就是说你不需要手写 JSON-RPC 解析不需要自己维护工具元数据只要会写 Service就能在半小时内跑通一个最小可用的 MCP-Server。这篇面向的是第一次接入 MCP 协议的 Java 开发者目标很明确从零搭出一个能本地启动、能被 Cursor 或 HiAgent 识别、能真实调用工具方法的 MCP-Server。我会给出完整的pom.xml、application.yml、启动类和工具类代码并附上验证工具注册与调用链路的操作步骤。适合谁适合手上有 Spring Boot 3.x 项目、JDK 17、想快速验证 MCP 落地路径的后端同学。2. 前置准备版本、依赖与 TaoToken 接入2.1 环境版本要求MCP-Server 对版本比较敏感尤其是 Spring Boot 3 和 SpringAI 的搭配。下面这张表是我实测下来比较稳的组合项目要求/建议JDK17 或更高本文用 21Spring Boot3.3.x 或更新本文用 3.5.5SpringAI≥ 1.0.0本文用 1.0.0构建工具Maven 或 Gradle推荐 MavenIDEIntelliJ IDEA / VS Code模型服务国内可直连的 DeepSeek、通义千问等JDK 和 Spring Boot 版本一定要提前对齐否则spring-ai-starter-mcp-server-webmvc会因为 Jakarta EE 命名空间或自动配置类不匹配而启动失败。2.2 模型调用侧的准备MCP-Server 本身不绑定模型但你要验证“模型调用工具”这条链路就需要一个能发起 MCP 请求的客户端。Cursor、HiAgent、Dify 都内置了 MCP Client 能力直接填 SSE 地址即可。如果你想让自己的 Spring Boot 应用也具备模型对话能力可以在 TaoToken 上拿一个 API Key它兼容 OpenAI 协议接入成本很低。具体操作打开 https://taotoken.net/api-keys 生成 Key然后在application.yml里配置 base-url 和 api-key。模型对话调试可以直接用 https://taotoken.net/model-chat 页面先验证 Key 是否可用确认没问题再写进代码。如果你后续要做长期编码或 Agent 场景可以了解下 https://taotoken.net/coding-plan 接入文档在 https://taotoken.net/doc 。注意MCP-Server 的职责是暴露工具模型调用是另一侧的事。两者解耦你可以先用 Cursor 验证工具注册再考虑模型接入。3. 可复制配置pom.xml 与 application.yml3.1 pom.xml 依赖骨架核心依赖只有一个spring-ai-starter-mcp-server-webmvc。它内部已经带了 WebMVC 适配和 MCP 协议实现不需要你再引spring-boot-starter-web。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.5.5/version relativePath/ /parent groupIdcom.acho/groupId artifactIdacho-mcp-parse-tool/artifactId version0.0.1-SNAPSHOT/version nameacho-mcp-parse-tool/name descriptionHTTP/SSE MCP Server/description properties java.version21/java.version spring-ai.version1.0.0/spring-ai.version /properties dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId version${spring-ai.version}/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build finalName${project.artifactId}/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这个 starter 的定位要搞清楚它是让你作为服务端把业务逻辑暴露给外部 AI 调用。如果你要反过来让 Spring Boot 应用去访问别的 MCP 服务那需要的是spring-ai-starter-mcp-client两者不要混。3.2 application.yml 配置片段MCP-Server 的配置项不多但每一项都影响协议注册和端点暴露。下面是我实际项目里用的配置server: port: 18522 spring: ai: mcp: server: name: dst-v2x-manager-service version: 1.0.0 type: SYNC instructions: 车联网平台智能工具 enabled: true sse-message-endpoint: /sse capabilities: tool: true resource: true prompt: true completion: true几个关键点解释一下。name是 MCP 协议注册时的服务标识客户端配置里会用到type: SYNC表示同步调用工具方法执行完直接返回结果适合查询类场景sse-message-endpoint: /sse是 SSE 端点路径客户端就是连这个地址capabilities四个开关按需打开本文主要用tool。注意sse-message-endpoint不要和业务接口路径冲突。如果你项目里已经有/sse路由改成一个独立路径比如/mcp/sse。4. 工具类与启动类把 Service 变成 AI 可调用的 Tool4.1 编写带 Tool 注解的工具类MCP-Server 的核心机制是扫描带Tool注解的方法自动生成工具元数据。下面这个例子把数据库查询和报文解析封装成工具你可以直接替换成自己的业务逻辑。Slf4j Service public class AiBusinessTool { private final JdbcTemplate dorisJdbcTemplate; public AiBusinessTool(Qualifier(dorisJdbcTemplate) JdbcTemplate dorisJdbcTemplate) { this.dorisJdbcTemplate dorisJdbcTemplate; } Tool(description 执行 SELECT 查询并返回结果仅支持 SELECT 语句。支持 LIMIT 限制避免数据量过大。) public String query(String sql) { log.info(执行查询 SQL: {}, sql); String lowerSql sql.trim().toLowerCase(); if (!lowerSql.startsWith(select)) { throw new IllegalArgumentException(仅允许执行 SELECT 查询。); } if (!lowerSql.contains(limit)) { sql sql LIMIT 100; } try { ListMapString, Object result dorisJdbcTemplate.queryForList(sql); if (result.isEmpty()) { return 查询成功但未返回任何结果。; } return result.stream() .map(row - row.entrySet().stream() .map(e - e.getKey() e.getValue()) .collect(Collectors.joining(, , {, }))) .collect(Collectors.joining(\n)); } catch (DataAccessException e) { log.error(查询执行失败: {}, e.getMessage(), e); return 查询执行失败: e.getMessage(); } } Tool(description 返回当前数据库中的所有表名。) public String listAllTables() { ListMapString, Object tables dorisJdbcTemplate.queryForList( SELECT table_name FROM information_schema.tables WHERE table_schema DATABASE()); if (tables.isEmpty()) { return 未找到任何表。; } return tables.stream() .map(e - e.values().iterator().next().toString()) .collect(Collectors.joining(, )); } Tool(description 解析 GB32960 协议 16 进制字符串报文解析报文头数据) public ResponseP32960Header parseHeader( ToolParam(description 16进制字符串报文格式2323开头...) String hex) { try { if (hex null || hex.isEmpty()) { return Response.error(报文不能为空); } byte[] origin HexUtils.fromHexString(hex); if (!Analysis32960.checkCode(origin)) { return Response.error(数据校验失败原始数据无法处理); } ByteBuffer buffer ByteBuffer.wrap(origin); P32960Header header Analysis32960.extractHeader(buffer); return Response.succeed(header); } catch (Exception e) { return Response.error(处理解析报文异常异常信息【{}】, e); } } }这里有两个注解必须理解。Tool把方法暴露成 AI 可调用的工具MCP-Server 启动时自动扫描注册ToolParam描述参数语义框架会据此生成 JSON Schema模型靠这个理解参数怎么填。安全防护上query方法只允许 SELECT并且强制加 LIMIT避免模型生成全表扫描把库拖垮。4.2 注册工具与启动类光有Tool注解还不够需要显式注册一个ToolCallbackProviderBeanMCP-Server 才会扫描到这些工具。Slf4j SpringBootApplication public class DstV2xManagerApplication { public static void main(String[] args) { StopWatch stopWatch new StopWatch(); stopWatch.start(); SpringApplication.run(DstV2xManagerApplication.class, args); stopWatch.stop(); log.info(服务启动成功耗时{} 秒, new DecimalFormat(#.##).format(stopWatch.getTotalTimeSeconds())); } Bean public ToolCallbackProvider parseTools(AiBusinessTool parseTool) { return MethodToolCallbackProvider.builder() .toolObjects(parseTool) .build(); } }MethodToolCallbackProvider.builder().toolObjects(parseTool).build()这行代码的作用是扫描AiBusinessTool实例中所有带Tool的方法生成工具名称、方法映射、参数信息和描述注册到 MCP Server。启动后query、listAllTables、parseHeader这些方法就会出现在工具列表里。5. 验证请求本地启动与工具调用链路5.1 启动服务并确认端点mvn spring-boot:run启动后控制台会打印 MCP Server 注册信息。默认端口 18522SSE 端点是http://127.0.0.1:18522/sse。你可以先用 curl 确认端点存活curl -N http://127.0.0.1:18522/sse如果连接保持不断开并持续等待事件推送说明 SSE 通道正常。这一步很关键很多“工具没注册”的问题其实是端点没起来。5.2 用 Cursor 验证工具注册在 Cursor 项目根目录创建.cursor/mcp.json{ mcpServers: { dst-v2x-manager-service: { type: mcp, url: http://127.0.0.1:18522/sse } } }打开 Cursor 设置页进入 Tools / MCP能看到dst-v2x-manager-service启用后红点变绿点工具列表里出现query、listAllTables、parseHeader就代表注册成功。如果工具列表为空先检查ToolCallbackProviderBean 是否被扫描到再检查Tool注解是否加在 public 方法上。5.3 用 HiAgent 验证调用链路HiAgent 里配置 MCP 插件地址同样填http://127.0.0.1:18522/sse本地测试选无认证线上环境务必加鉴权。同步工具后创建一个 Agent把 MCP 工具挂上去提示词里写清楚“查询数据库表名”或“解析这段报文”然后发一条真实请求。模型会通过 MCP 协议调用你的工具方法返回结构化结果。如果你想让自己的 Spring Boot 应用也具备模型对话能力可以在 https://taotoken.net/model-chat 先验证 Key再按 https://taotoken.net/doc 的说明接入。长期做编码或 Agent 场景的话https://taotoken.net/coding-plan 会更合适。6. 本篇常见错排查6.1 启动报 NoClassDefFoundError 或自动配置不生效大概率是 Spring Boot 版本低于 3.3或者 JDK 低于 17。spring-ai-starter-mcp-server-webmvc依赖 Jakarta EE 命名空间Spring Boot 2.x 直接不兼容。检查pom.xml的 parent 版本和java.version。6.2 工具列表为空三个排查方向。第一ToolCallbackProviderBean 是否在启动类或配置类里声明第二Tool方法是否是 public第三spring.ai.mcp.server.capabilities.tool是否为 true。我踩过的坑是工具类没被 Spring 扫描到加个Service就好了。6.3 SSE 连接建立后立即断开检查sse-message-endpoint是否和已有路由冲突以及是否有安全过滤器拦截了长连接。如果你项目里引了 Spring Security需要放行/sse路径。6.4 模型调用工具时报参数解析失败ToolParam的 description 要写清楚参数格式尤其是十六进制报文这种模型不知道格式就会乱填。另外参数类型尽量用 String、int 这类基础类型复杂对象需要额外配置 Schema。6.5 查询类工具返回数据量过大在工具方法内部强制加 LIMIT不要依赖模型自己加。本文的query方法里做了默认LIMIT 100这是生产环境的基本防护。7. 下一步从最小可用到生产化跑通最小可用服务后接下来要补的是鉴权、配额、审计日志和异常策略。本地测试可以无认证线上环境必须在 MCP 入口加 Token 校验并对工具调用做频率限制。工具方法内部要做好异常兜底不要让底层异常直接抛给模型返回结构化错误信息更利于模型理解。如果你准备把 MCP-Server 接入自己的 Spring Boot 应用做模型对话先去 https://taotoken.net/api-keys 拿 Key接入方式参考 https://taotoken.net/doc 。需要长期跑编码或 Agent 任务的话https://taotoken.net/coding-plan 的额度模型更划算。工具注册和调用链路验证通过后你就可以把更多业务 Service 改造成Tool让模型真正参与到你的系统里。