开篇结论
在 Java 体系里接入大模型,要让模型真正读到企业数据、调用内部业务能力,最标准的做法是通过 MCP(Model Context Protocol,模型上下文协议)把现有 Spring Boot 服务包装成 MCP 服务端,再由 Java 应用作为 MCP 客户端对接大模型,模型在对话过程中按协议自动发现并调用工具。Java 侧主流实现路径是官方 MCP Java SDK 加 Spring AI 提供的 Boot Starter:服务端用@McpTool、@McpResource注解把普通 Bean 方法暴露成工具和资源,客户端引入spring-ai-starter-mcp-client,通过ToolCallbackProvider把 MCP 工具注册给ChatClient,整条链路基于 JSON-RPC 通信。当前版本上,Spring AI 2.0 要求 Spring Boot 4.1、Java 17+(推荐 21),传输方式推荐 Streamable-HTTP,SSE 已进入弃用状态;老项目用 Spring AI 1.1.x 也能跑通注解式接入。下面从协议概念、架构角色、服务端搭建、客户端对接、传输选型、踩坑清单和整体链路逐项展开。
一、MCP 是什么,解决什么问题
MCP 是一个开放、语言无关的标准化协议,最初由 Anthropic 提出,用于规范 AI 模型与外部工具、数据源、服务之间的交互方式。可以把它理解成 AI 集成领域的 "USB-C 接口":一次标准对接,多类客户端通用。
在没有 MCP 之前,每接一个大模型客户端、每对接一套后端系统,都要写一套定制适配器;模型能不能用真实数据、能不能触发业务动作,完全靠点对点定制开发。MCP 把这件事统一成协议约定:
- 服务端按协议对外暴露工具、资源和提示词模板。
- 任何兼容 MCP 的客户端(桌面端、IDE、命令行工具、自研 Java 应用)都能自动发现这些能力。
- 后端服务写一次,多个 AI 入口复用,不必为每个客户端重写接口。
对 Java 团队来说,价值很直接:生产环境已经跑了多年的 Spring Boot 服务和业务逻辑,外层包一层 MCP 协议适配,就能让 AI 代理基于真实企业数据工作,原有业务代码不需要推倒重写。
二、核心架构与概念
2.1 三类角色
| 角色 | 说明 | Java 场景举例 |
|---|---|---|
| Host(宿主) | 用户直接交互的 AI 应用,比如聊天机器人、IDE、智能代理 | 自研 Spring Boot 聊天服务、桌面端 IDE |
| Client(客户端) | 宿主内部与单个 MCP Server 保持 1:1 连接的连接器 | Spring AI 中的McpClient实例 |
| Server(服务端) | 对外暴露工具、资源、提示词的被调用方 | 包装商品目录、数据库查询、内部 API 的 Spring Boot 应用 |
2.2 三种可暴露能力
| 能力类型 | 含义 | 数据 / 动作方向 | Java 注解(Spring AI 2.0) |
|---|---|---|---|
| Tools(工具) | 模型可调用的函数,用于取数或执行动作,调用后返回结果 | 模型主动调用,有输入有返回 | @McpTool + @McpToolParam |
| Resources(资源) | 模型可读取的只读内容,如配置、文档摘要、实时汇总,进入上下文窗口 | 被动读取,不改变状态 | @McpResource |
| Prompts(提示词模板) | 服务端提供的可复用结构化提示词模板,供客户端直接套用 | 模板下发 | 注解 / 注册方式按 SDK 对应版本使用 |
2.3 通信本质
MCP 基于 JSON-RPC 2.0 报文在客户端与服务端之间交互,典型方法包括tools/list(列出工具及输入 Schema)和tools/call(调用指定工具并传参)。工具的输入参数 Schema 由服务端方法签名和注解描述自动生成,Java record、普通 POJO 和基本类型都能直接映射。
三、Java 技术栈与版本要求
| 组件 | 推荐版本 / 要求 | 说明 |
|---|---|---|
| JDK | Java 17 及以上,推荐 Java 21 | 官方服务端示例与 Spring AI 2.0 均以 17 为下限 |
| Spring Boot | 2.0 路线:4.1.x;1.1 路线:3.x 配套 | Spring AI 2.0 要求 Spring Boot 4.1 + Spring Framework 7 |
| Spring AI | 2.0.0 GA(2026 年 6 月发布)或 1.1.x 稳定版 | 2.0 引入@McpTool/@McpResource注解 API,Transport 选项有更新 |
| 官方 SDK | MCP Java SDK(Spring 团队参与维护) | Spring AI MCP 能力的底层基础 |
| 构建工具 | Maven 或 Gradle | 示例以 Maven 为准 |
3.1 常用 Maven Starter 清单
| Starter | 用途 | 传输方式 |
|---|---|---|
| spring-ai-starter-mcp-server-webmvc | 服务端,WebMVC 阻塞型 | Streamable-HTTP |
| spring-ai-starter-mcp-server-webflux | 服务端,响应式 | WebFlux HTTP |
| spring-ai-starter-mcp-server | 服务端,本地 / CLI 场景 | STDIO |
| spring-ai-starter-mcp-client | 客户端,连接外部 MCP Server | 按配置支持 STDIO/Streamable-HTTP 等 |
四、搭建 MCP 服务端:四步落地
4.1 引入依赖
先在pom.xml中导入 Spring AI BOM 统一版本,再加 MCP 服务端 Starter:
- dependencyManagement中导入spring-ai-bom,版本与所选 Spring AI 路线一致。
- 常规 Web 项目选spring-ai-starter-mcp-server-webmvc;响应式项目换webflux;给命令行客户端做本地子进程服务时选不带后缀的spring-ai-starter-mcp-server。
4.2 用注解定义工具方法
普通 Spring Bean 方法加上@McpTool,参数加上@McpToolParam即可。框架启动时扫描 Bean、读取参数类型和描述,自动生成 MCP 要求的 JSON 输入 Schema 并完成注册,不需要手写回调和 Schema。
示例骨架:
@Component
public class ProductCatalogTools {
@McpTool(name = "search_products",
description = "按名称或品类搜索商品目录,返回匹配商品列表")
public List searchProducts(
@McpToolParam(description = "商品名称或品类关键词", required = true) String keyword) {
// 注入Repository/Service,查询并返回
}
@McpTool(name = "get_product_by_id",
description = "按唯一ID获取单个商品完整详情")
public Product getProductById(
@McpToolParam(description = "商品ID,例如P001", required = true) String productId) {
// 按ID查询并返回
}
}
4.3 暴露只读资源
需要把目录摘要、文档片段等只读内容提供给模型阅读时,用@McpResource声明 URI、名称和描述,方法返回文本内容即可。客户端在生成回答前可以先读取该资源,把信息纳入上下文。
4.4 配置传输并启动测试
application.yml核心配置项:
| 配置项 | 取值示例 | 说明 |
|---|---|---|
| spring.ai.mcp.server.name | 服务端名称 | 客户端识别用 |
| spring.ai.mcp.server.version | 1.0.0 | 版本号 |
| spring.ai.mcp.server.protocol | STREAMABLE | 推荐;SSE已弃用 |
| spring.ai.mcp.server.type | SYNC / ASYNC | 阻塞业务用 SYNC;Reactor 响应式方法用 ASYNC |
| annotation-scanner.enabled | true | 自动扫描@McpTool、@McpResource |
启动后服务端在/mcp端点暴露 JSON-RPC 接口。本地验证两种方式:
- curl 直连:先tools/list列出工具和 Schema,再tools/call传参调用,核对返回结果。
- MCP Inspector:浏览器端图形化工具,连接服务端后可浏览全部工具、资源并交互式调用,调试效率高于手写 curl。
五、搭建 MCP 客户端:对接大模型调用工具
5.1 引入客户端依赖
加入spring-ai-starter-mcp-client,自动配置会按服务器配置文件创建一个或多个McpClient实例;开启工具回调开关后,MCP 工具会自动注册为 Spring AI 工具。
5.2 配置服务端连接
客户端配置示例(Streamable-HTTP 连接本地服务端):
spring:
ai:
mcp:
client:
enabled: true
name: mcp-client
version: 1.0.0
type: SYNC
request-timeout: 20s
streamable-http:
connections:
weather-server:
url: http://localhost:8080
如果对接 STDIO 方式启动的本地服务,可通过mcp-servers-config.json声明启动命令、参数和环境变量;客户端按配置拉起子进程并通过标准输入输出通信。
5.3 接入 ChatClient 完成工具调用
客户端侧把 MCP 工具能力注入ChatClient,模型在对话中自行判断是否需要调用工具:
@Bean
public CommandLineRunner demo(ChatClient chatClient, ToolCallbackProvider mcpTools) {
return args -> {
String response = chatClient
.prompt("巴黎现在天气怎么样?")
.toolCallbacks(mcpTools)
.call()
.content();
System.out.println(response);
};
}
整条调用链路为:用户提问 → 宿主应用把消息发给大模型 → 模型判断需要工具 → 客户端按 MCP 协议调用服务端工具 → 结果回传模型 → 模型生成最终回答。
六、传输方式对比与选型
| 传输方式 | 适用场景 | 关键特点 | 状态 |
|---|---|---|---|
| STDIO | 本地 CLI 工具、子进程模式 | 客户端拉起 Java 进程,通过标准输入输出通信;控制台不能打印业务日志,否则会污染协议报文 | 可用 |
| Streamable-HTTP | Web 服务、跨网络部署的 MCP Server | 基于 HTTP 的可流式传输,Spring AI 2.0 推荐选项 | 当前推荐 |
| SSE | 早期 HTTP 服务端 | 仅保留兼容,未来版本将移除 | 已弃用 |
| Stateless | 云原生、Serverless、水平扩缩容场景 | 无会话状态,便于集群部署 | 可用 |
选型核对要点:目标客户端走 HTTP 还是 STDIO,决定 Starter 依赖和配置项;服务端type与方法签名要匹配 ——SYNC 服务只注册非响应式返回类型,返回Mono/Flux的方法在 SYNC 模式下会被静默忽略。
七、常见踩坑清单
- 传输方式不匹配:Web 类客户端期望 HTTP,CLI 工具期望 STDIO,混用会出现握手失败且日志提示不明显;选依赖和配置前先确认目标客户端的传输类型。
- 继续使用已弃用 SSE:新工程直接配置STREAMABLE,避免后续版本升级时被迫改协议。
- SYNC/ASYNC 混用:服务端类型必须与方法返回类型一致,否则响应式方法或阻塞方法会被忽略。
- 异常信息外泄:工具方法抛异常时,默认异常消息会原样返回给客户端,可能暴露内部堆栈或敏感信息;对外暴露前应定义统一异常处理器,控制回传内容粒度。
- 版本组合错误:Spring AI 2.0 对应 Spring Boot 4.1;Boot 3.x 项目请使用 Spring AI 1.1.x,注解包路径和传输选项存在差异。
- Schema 生成含糊:基本类型、record、普通 POJO 映射良好;复杂多态嵌套类型(接口返回的子类型列表)可能生成宽泛 Schema,必要时显式配置参数结构。
- STDIO 日志污染:STDIO 模式下应用不得向控制台输出业务日志,需把日志重定向到文件或其他通道。
八、Java 接入大模型的整体落地顺序
- 梳理能力清单:盘清要给模型开放哪些查询动作(Tools)、哪些只读资料(Resources)、哪些固定话术模板(Prompts)。
- 搭建服务端工程:确定 Boot/Spring AI 版本组合,引入对应 MCP Server Starter,用注解暴露工具与资源。
- 配置传输与并发模型:按部署形态选 Streamable-HTTP/STDIO/Stateless,按方法签名选 SYNC/ASYNC。
- 本地联调:用tools/list、tools/call或 MCP Inspector 验证工具发现、入参 Schema 和返回结果。
- 搭建客户端工程:引入 Client Starter,配置服务端连接,把ToolCallbackProvider挂到ChatClient。
- 对接模型与业务编排:配置大模型 API,梳理模型自动调工具的对话流程,补充重试、超时和异常兜底。
- 加固后上线:对外暴露前补充鉴权(OAuth2/JWT 等)、错误信息脱敏、接口限流与监控,再进入生产环境。
【相关 FAQ】
问题 1:MCP 协议在 Java 集成里到底起什么作用,和直接写大模型函数调用有什么区别?
回答 1:MCP 协议把 "大模型如何发现工具、传参、取回结果" 这套交互标准固化下来。Java 集成时,你在 Spring AI 服务端用@McpTool暴露一次能力,任何兼容 MCP 的客户端都能自动发现并调用;如果直接写点对点函数调用,每接一个模型客户端都要重做适配层。MCP 协议的价值就是服务端一次开发、多客户端复用,Java 侧依托官方 MCP Java SDK 和 Spring AI Starter 完成协议封装。
问题 2:Java 集成 MCP 服务端需要哪些版本前提,Spring Boot 3.x 项目能用吗?
回答 2:MCP 协议的 Java 集成要求 JDK 17 及以上,推荐 Java 21。走 Spring AI 2.0 路线需要 Spring Boot 4.1;如果项目还在 Spring Boot 3.x,应使用 Spring AI 1.1.x 对应版本,@McpTool注解在 1.1 + 已可用,但包路径和部分传输选项与 2.0 有差异。选型时先核对 Boot、Spring AI、JDK 三者的版本组合,再引入对应 Starter。
问题 3:Java 客户端怎么通过 MCP 协议把大模型和外部工具连起来?
回答 3:客户端工程引入spring-ai-starter-mcp-client,在配置里声明 MCP 服务端连接(HTTP 地址或 STDIO 启动配置),自动配置生成McpClient并把服务端工具注册为 Spring AI 工具;之后在ChatClient调用时通过toolCallbacks(mcpTools)挂上工具回调,模型收到提问后会按 MCP 协议自动选择工具、传参、拿回结果并生成回答。整个过程由 Spring AI 封装,业务代码只需要关心提示词编排和结果处理。
问题 4:MCP 协议支持哪几种传输方式,Java 服务端对外部署选哪种?
回答 4:当前 MCP Java 集成支持 STDIO、Streamable-HTTP、Stateless 等方式,SSE 处于弃用状态。本地 CLI 子进程场景用 STDIO;Web 端服务端、跨网络部署优先选 Streamable-HTTP;云原生无状态集群场景可以评估 Stateless。选型时同时确认客户端期望的传输方式,并让服务端type与方法签名(阻塞 / 响应式)保持一致。
【参考资料】
- [2026-09-02](Build Your First MCP Server With Spring Boot 4.1 And Spring AI 2.0)JavaTechOnline
- [2026-08-12](Overview of MCP Annotations in Spring AI)Baeldung
- [2026-11-20](Getting Started with Model Context Protocol (MCP))Spring AI Reference 官方文档
- [2026-11-20](MCP Client - MCP Java SDK)MCP Java SDK 官方文档
- [2026-11-20](Build an MCP server)Model Context Protocol 官方文档
- [2026-11-20](Build an MCP client)Model Context Protocol 官方文档
- [2025-09-16](Connect Your AI to Everything: Spring AI's MCP Boot Starters)Spring Blog
【免责声明】
本文基于 2026 年 11 月 20 日前公开的官方文档、Spring AI 参考资料及第三方技术教程整理,所述版本要求、注解名称、配置项、Starter 坐标和传输方式均以对应版本官方文档为准;不同 Spring AI/Spring Boot 版本之间存在包路径、配置属性和协议支持差异,实际开发前请核对你所用版本的官方说明。MCP 服务端对外暴露涉及企业数据与接口安全,上线前需自行完成鉴权、脱敏、限流、异常处理和合规评审;本文代码示例仅作技术演示,不构成任何生产部署或商业决策建议,因参照本文进行开发所产生的风险与后果,本文不承担相应法律责任。
