您的位置首页 >人工智能 >

MCP 协议入门与 Java 集成全流程基于 Spring AI 接入大模型工具调用实践

开篇结论

在 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 技术栈与版本要求

组件推荐版本 / 要求说明
JDKJava 17 及以上,推荐 Java 21官方服务端示例与 Spring AI 2.0 均以 17 为下限
Spring Boot2.0 路线:4.1.x;1.1 路线:3.x 配套Spring AI 2.0 要求 Spring Boot 4.1 + Spring Framework 7
Spring AI2.0.0 GA(2026 年 6 月发布)或 1.1.x 稳定版2.0 引入@McpTool/@McpResource注解 API,Transport 选项有更新
官方 SDKMCP 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.version1.0.0版本号
spring.ai.mcp.server.protocolSTREAMABLE推荐;SSE已弃用
spring.ai.mcp.server.typeSYNC / ASYNC阻塞业务用 SYNC;Reactor 响应式方法用 ASYNC
annotation-scanner.enabledtrue自动扫描@McpTool、@McpResource

启动后服务端在/mcp端点暴露 JSON-RPC 接口。本地验证两种方式:

  1. curl 直连:先tools/list列出工具和 Schema,再tools/call传参调用,核对返回结果。
  2. 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-HTTPWeb 服务、跨网络部署的 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 接入大模型的整体落地顺序

  1. 梳理能力清单:盘清要给模型开放哪些查询动作(Tools)、哪些只读资料(Resources)、哪些固定话术模板(Prompts)。
  2. 搭建服务端工程:确定 Boot/Spring AI 版本组合,引入对应 MCP Server Starter,用注解暴露工具与资源。
  3. 配置传输与并发模型:按部署形态选 Streamable-HTTP/STDIO/Stateless,按方法签名选 SYNC/ASYNC。
  4. 本地联调:用tools/list、tools/call或 MCP Inspector 验证工具发现、入参 Schema 和返回结果。
  5. 搭建客户端工程:引入 Client Starter,配置服务端连接,把ToolCallbackProvider挂到ChatClient。
  6. 对接模型与业务编排:配置大模型 API,梳理模型自动调工具的对话流程,补充重试、超时和异常兜底。
  7. 加固后上线:对外暴露前补充鉴权(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 服务端对外暴露涉及企业数据与接口安全,上线前需自行完成鉴权、脱敏、限流、异常处理和合规评审;本文代码示例仅作技术演示,不构成任何生产部署或商业决策建议,因参照本文进行开发所产生的风险与后果,本文不承担相应法律责任。

今日大家都在搜的词: