1. 从零理解 SpringAI 搭建 MCP 到底解决什么问题如果你是一名 Java 开发者最近大概率被 MCP 这个词刷屏了。MCP 全称 Model Context Protocol翻译过来叫模型上下文协议它要解决的核心问题其实很朴素大模型本身只会聊天它不知道你公司内部的套餐数据、查不到实时天气、也没法帮你下单支付。过去我们靠写一堆 RestFul 接口再让前端页面一步步引导用户操作现在换了个思路把这些能力包装成 MCP 工具直接交给大模型去调用用户一句话就能完成原本需要跳转三四个页面的流程。SpringAI 是 Spring 官方推出的 AI 应用开发框架它把大模型调用、提示词管理、向量知识库、工具调用这些能力都做成了 Spring 风格的 Bean 和注解。而 SpringAI 对 MCP 的支持让你可以用写Service的方式把一个普通方法暴露成 MCP 工具。这对 Java 开发者来说门槛极低不需要去学 Python也不需要理解复杂的协议底层只要会写 Spring Boot 就能上手。这篇文章面向的是第一次接触 MCP 协议的 Java 开发者。我会带你从零搭建一个天气查询的 MCP 服务给出可以直接复制的pom.xml依赖、application.yml配置和 MCP Server 注册代码然后用 Inspector 逐项验证工具是否暴露成功、调用链路是否连通。整个过程你可以在本地完整跑通不需要任何特殊网络环境。先说清楚适合谁看如果你已经会 Spring Boot 基础知道什么是 Bean、什么是依赖注入那这篇内容你完全可以跟做。如果你还没接触过 SpringAI也没关系我会把每个配置项的作用讲明白。整条链路是写一个 Spring Boot 应用用Tool注解定义工具方法通过 SpringAI 的 MCP Server 自动配置把它暴露成 SSE 端点最后用 Inspector 这个调试工具像 Postman 一样去调用验证。我试过把这套流程走通之后最大的感受是 MCP 并没有想象中那么神秘。它本质上就是一套约定好的接口规范让大模型知道有哪些工具可以调、每个工具需要什么参数、返回什么结果。SpringAI 帮你把这套规范封装好了你只需要专注在业务逻辑本身。接下来我们一步步来。2. TaoToken 前置准备与 SpringAI MCP 环境依赖配置在正式写代码之前有一个前置环节需要先处理好那就是大模型的接入凭证。因为 MCP 服务本身只是工具提供方真正去调用这些工具的是大模型所以你需要一个能访问大模型 API 的入口。这里我用 TaoToken 来做统一接入它的好处是兼容 OpenAI 风格的接口配置简单而且提供了模型对话、Coding Plan、API Keys 管理等一整套能力适合我们这种需要反复调试的场景。你可以先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解一下整体功能然后进入控制台创建 API Key。API 的基础地址是 https://taotoken.net/api 注意这个地址后面拼接路径时不要再加多余的斜杠。创建好的 Key 要妥善保存后面配置客户端和验证请求都会用到。环境方面你需要准备 JDK 17 或更高版本这是 Spring Boot 3.x 的硬性要求。构建工具用 Maven 就行。IDE 随意IntelliJ IDEA 或者 VS Code 都可以。另外 Inspector 是通过 npx 启动的所以本机需要有 Node.js 环境建议 18 以上版本。这些装好之后我们就可以开始建工程了。关于模型的选择如果你只是做工具链调试用模型对话功能里的通用模型就够了如果你打算长期做编码和 Agent 开发可以关注一下 Coding Plan它在长上下文和工具调用稳定性上更适合工程场景。API Keys 的管理入口在控制台里建议给不同的项目建不同的 Key方便排查问题时定位来源。接入文档里对各个端点的说明比较清楚遇到不确定的参数可以对照着看。这里要提醒一句MCP 服务和大模型是解耦的。你的 MCP Server 跑在本地 8082 端口它只负责暴露工具大模型通过客户端去连接这个 Server发现工具并调用。所以调试的时候你可以先用 Inspector 单独验证 MCP Server 是否正常再去接大模型这样出问题容易定位。很多人一上来就把两边接在一起结果报错了不知道是 Server 的问题还是客户端的问题排查起来很痛苦。3. 可复制的 pom 依赖与 application.yml 完整配置这一节是全文的核心所有配置我都会给全你直接复制就能用。先看pom.xml。父工程用 Spring Boot 3.4.5JDK 17。依赖部分需要引入 WebFlux因为 MCP 的 SSE 传输基于响应式、SpringAI 的 MCP Server 自动配置、SpringAI MCP 核心包以及 MCP 官方的 WebFlux 实现。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-autoconfigure/artifactId version1.0.0-M6/version scopecompile/scope /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp/artifactId version1.0.0-M6/version scopecompile/scope /dependency dependency groupIdio.modelcontextprotocol.sdk/groupId artifactIdmcp-spring-webflux/artifactId version0.8.0/version scopecompile/scope /dependency /dependencies这里版本号要特别注意SpringAI 的 MCP 支持在 1.0.0-M6 这个里程碑版本里比较稳定MCP SDK 用 0.8.0。如果你用了不匹配的版本启动时会出现类找不到或者方法签名对不上的报错。我踩过的坑就是一开始用了快照版本结果ToolCallbackProvider的包路径变了编译直接失败。接下来是application.yml。这个文件决定了 MCP Server 的名字、SSE 端点路径、消息端点路径和传输类型。server: port: 8082 spring: ai: mcp: server: name: my-weather-server sse-endpoint: /sse sse-message-endpoint: /mcp/messages type: ASYNC version: 0.0.1逐项说明一下。name是 MCP Server 的标识客户端连接时会看到这个名字。sse-endpoint是客户端建立 SSE 长连接的路径默认就是/sse。sse-message-endpoint是客户端发送消息的路径注意它和 SSE 端点不是同一个。type设为ASYNC表示异步处理适合工具调用可能耗时的场景。version是版本号方便后续做兼容管理。如果你打算把这个 MCP Server 接入到 Claude Code 或者 Cline 这类客户端配置里需要写全三件套Base URL、Key、Model ID。Base URL 就是你的 MCP Server 地址加 SSE 端点比如http://localhost:8082/sseKey 是 TaoToken 那边创建的 API KeyModel ID 根据你选的模型填。这三样缺一不可尤其是 Model ID 写错会直接导致工具调用失败。配置写完之后启动类里需要注册工具回调提供者。代码如下SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } Bean public ToolCallbackProvider weatherTools(OpenMeteoService openMeteoService) { return MethodToolCallbackProvider.builder() .toolObjects(openMeteoService) .build(); } }这个 Bean 的作用是把OpenMeteoService里所有标注了Tool的方法收集起来注册成 MCP 工具。MethodToolCallbackProvider是 SpringAI 提供的工具回调提供者它会扫描传入对象的方法注解自动生成工具描述和参数 schema。这一步是连接普通 Java 方法和MCP 工具的桥梁少了它你的方法就只是普通方法不会被暴露出去。4. 编写 MCP Server 工具类并验证请求成功结果工具类的写法其实很直观就是按照 MCP 的规范用注解把方法标记成工具并描述清楚每个参数的含义。我们以 Open-Meteo 这个免费天气 API 为例它提供了按经纬度查询天气的能力。下面这个OpenMeteoService定义了两个工具一个查天气预报一个查空气质量。Service public class OpenMeteoService { private final WebClient webClient; public OpenMeteoService(WebClient.Builder webClientBuilder) { this.webClient webClientBuilder .baseUrl(https://api.open-meteo.com/v1) .build(); } Tool(description 根据经纬度获取天气预报) public String getWeatherForecastByLocation( ToolParam(description 纬度例如39.9042) String latitude, ToolParam(description 经度例如116.4074) String longitude) { try { String response webClient.get() .uri(uriBuilder - uriBuilder .path(/forecast) .queryParam(latitude, latitude) .queryParam(longitude, longitude) .queryParam(current, temperature_2m,wind_speed_10m) .queryParam(timezone, auto) .build()) .retrieve() .bodyToMono(String.class) .block(); return 当前位置纬度 latitude 经度 longitude 的天气信息\n response; } catch (Exception e) { return 获取天气信息失败 e.getMessage(); } } Tool(description 根据经纬度获取空气质量信息) public String getAirQuality( ToolParam(description 纬度例如39.9042) String latitude, ToolParam(description 经度例如116.4074) String longitude) { return 当前位置纬度 latitude 经度 longitude 的空气质量\n - PM2.5: 15 μg/m³ (优)\n - PM10: 28 μg/m³ (良)\n - 空气质量指数(AQI): 42 (优)\n - 主要污染物: 无; } }Tool注解里的description非常重要大模型就是靠这段描述来判断这个工具是干什么的、什么时候该调用它。描述写得越清楚模型选错工具的概率越低。ToolParam里的描述同样关键它告诉模型每个参数该填什么。比如纬度参数我写了例如39.9042模型就知道要传一个数值型的字符串。启动应用后你会看到控制台打印出 MCP Server 注册的工具列表。这时候打开浏览器访问http://localhost:8082/sse如果看到连接保持打开状态并且有事件流输出说明 SSE 端点正常。接下来用 Inspector 来验证。执行下面的命令npx modelcontextprotocol/inspectorInspector 启动后会打开一个网页界面默认地址是http://localhost:6274。在界面里选择传输类型为 SSEURL 填http://localhost:8082/sse点击连接。连接成功后左侧会列出所有已注册的工具你应该能看到getWeatherForecastByLocation和getAirQuality两个工具。点开getWeatherForecastByLocation在参数区填入纬度39.9042和经度116.4074点击调用。如果一切正常右侧会返回北京的实时天气数据包含温度和风速。这一步成功说明你的 MCP Server 工具暴露和调用链路完全连通了。同样的方式测试getAirQuality它会返回模拟的空气质量数据。验证通过后你就可以把这个 MCP Server 接入到支持 MCP 的客户端了。比如在 Cline 里配置 MCP Server 地址或者在 Dify 里添加自定义工具。接入时记得把 Base URL、Key、Model ID 三件套配全。模型对话功能可以用来快速测试工具调用是否符合预期而如果你要做长期的 Agent 开发Coding Plan 在工具链稳定性和上下文管理上会更省心。5. 本篇常见错误排查401、local proxy failed 与 reading choices调试 MCP 的过程中有几个报错几乎每个人都会遇到。我把它们整理出来对照着排查能省不少时间。第一个是401 Unauthorized。这个通常出现在客户端连接大模型 API 的时候说明你的 API Key 不对或者没传。检查两点一是 Key 是否复制完整有没有多余空格二是请求头里的认证格式是否正确TaoToken 兼容 OpenAI 风格一般是Authorization: Bearer 你的Key。如果 Key 是对的还报 401那可能是 Key 被禁用或者额度用完了去控制台确认一下状态。第二个是local proxy failed或者类似的连接失败提示。这个多半是 MCP Server 没启动或者端口被占用。先确认 8082 端口有没有被其他程序占用可以用lsof -i:8082或者netstat -ano | findstr 8082查看。如果端口正常检查 Inspector 里填的 URL 是不是http://localhost:8082/sse注意协议是 http 不是 https路径是/sse不是/mcp/messages。这两个端点容易搞混/sse是建立连接的/mcp/messages是发消息的Inspector 连接时用前者。第三个是reading choices相关的报错完整信息可能是Cannot read properties of undefined (reading choices)。这个一般出现在客户端解析大模型响应的时候说明返回的数据结构不符合预期。常见原因是模型 ID 填错了或者请求体格式不对。检查你配置的 Model ID 是否和 TaoToken 支持的模型列表一致请求体里messages字段的格式是否正确。如果用的是流式响应还要确认客户端是否支持 SSE 解析。第四个是 OAuth 相关的报错。有些 MCP 客户端在连接远程 Server 时会走 OAuth 流程如果你用的是本地 Server一般不需要 OAuth。如果看到 OAuth 报错检查客户端配置里是不是误开了认证选项。本地调试阶段把认证关掉直接用 SSE 连接即可。还有一个容易被忽略的问题SpringAI 版本和 MCP SDK 版本不匹配。如果你看到NoSuchMethodError或者ClassNotFoundException先核对pom.xml里的版本号。spring-ai-mcp-server-spring-boot-autoconfigure和spring-ai-mcp要用同一个版本MCP SDK 用 0.8.0。版本对了大部分编译和启动问题都会消失。排查的时候有个小技巧先单独验证 MCP Server用 Inspector 直连确认工具能列出、能调用。这一步过了再去接大模型客户端。如果 Inspector 都连不上那问题一定在 Server 端跟大模型无关。这样分层排查效率会高很多。6. 把 MCP 工具链接入真实 Agent 的下一步工具能在 Inspector 里调通只是第一步。真正让 MCP 发挥价值是把它接入到 Agent 里让大模型自主决定什么时候调用哪个工具。这时候你需要一个支持 MCP 的客户端比如 Cline、Dify或者用 SpringAI 自己写一个客户端。客户端的配置核心还是那三件套Base URL 指向你的 MCP Server SSE 端点Key 用 TaoToken 创建的凭证Model ID 选一个工具调用能力强的模型。接入之后你可以试着用自然语言提问比如帮我查一下北京现在的天气观察模型是否会自动调用getWeatherForecastByLocation工具并把经纬度参数填对。如果模型没有调用工具而是直接编造了一个答案说明工具描述不够清晰或者模型的工具调用能力不足。这时候可以优化Tool的 description把使用场景写得更明确。对于需要长期做编码和 Agent 开发的场景建议把 API Key 的管理规范化不同环境用不同的 Key方便追踪调用来源和排查问题。接入文档里有关于端点、参数、错误码的详细说明遇到不确定的地方可以随时查阅。模型对话功能适合快速验证工具调用逻辑而 Coding Plan 更适合需要稳定长上下文和复杂工具链的工程场景。最后留一个实用建议MCP Server 的工具粒度不要太细也不要太粗。太细会导致模型需要调用很多次才能完成一个任务太粗则会让单个工具的参数过于复杂模型容易填错。像天气查询这种一个工具负责一个明确的能力参数控制在两三个以内是比较理想的粒度。你可以从这个天气服务开始逐步把公司内部的查询、下单、支付等能力都包装成 MCP 工具让 Agent 真正跑起来。