文章目录
- [1. MCP Java SDK](#1. MCP Java SDK)
-
- [1.1 概述](#1.1 概述)
- [1.2 版本说明](#1.2 版本说明)
- [1.3 三层架构](#1.3 三层架构)
-
- 1.3.1客户端/服务端层（顶层）
- [1.3.2 会话层（中层）](#1.3.2 会话层（中层）)
- [1.3.3 传输层（底层）](#1.3.3 传输层（底层）)
- [2. Spring AI 集成 MCP](#2. Spring AI 集成 MCP)
-
- [2.1 客户端 Starters](#2.1 客户端 Starters)
- [2.2 服务端 Starters](#2.2 服务端 Starters)
- [2.3 MCP 注解](#2.3 MCP 注解)
- [2.4 相关参考文档](#2.4 相关参考文档)
1. MCP Java SDK
1.1 概述
MCP Java SDK 是模型上下文协议的 Java 语言实现，依托同步、异步两种通信模式，实现 AI 模型与工具之间的标准化交互。
1.2 版本说明
2026 年 2 月份，才发布了 1.0.0 正式版本，过渡到稳定、语义版本化的发布线：
2026 年 3 月 14 日，发布了 1.1.0 正式版本：
SDK 支持 2025-06-18 的 MCP 规范，并支持在 2024-11-05 、 2025-03-26 和 2025-06-18 之间进行协议版本协商。 2025-11-25 规范的工作正在积极进行中：
1.x 版本的路线图可以参考官方文档说明。
1.3 三层架构
Java 版 MCP 采用三层架构，职责分离，便于维护与扩展：
1.3.1客户端/服务端层（顶层）
负责核心业务逻辑与协议操作：
- McpClient：管理客户端逻辑与服务端连接
- McpServer：处理服务端协议逻辑与客户端请求
客户端
MCP 客户端是协议架构的核心组件，负责建立并维护与 MCP 服务端的连接，实现协议客户端逻辑，主要能力包括：
- 协议版本协商，保障与服务端兼容
- 能力协商，确认双方可用功能
- 消息传输与
JSON-RPC通信 - 工具发现与调用执行
- 资源访问与管理
- 交互提示词系统
可选扩展能力：
- 根路径管理
- 采样能力支持
- 同步、异步双模式操作
传输方式：
- 标准输入输出传输：适用于进程间通信
- 基于
Java原生HttpClient的SSE客户端传输 - 基于
WebFlux的SSE客户端传输：适配响应式HTTP流式场景
Java SDK 实现了协议的客户端部分：
服务端
MCP 服务端为架构基础组件，向客户端提供工具、资源与各项能力，实现协议服务端逻辑，
主要职责：
- 实现服务端协议相关逻辑
- 对外暴露工具并支持工具发现
- 基于URI实现资源管理与访问
- 提供并处理提示词模板
- 与客户端进行能力协商
- 结构化日志与消息通知
- 多客户端并发连接管理
- 同步、异步API兼容
支持的传输方式：
- 标准输入输出(
STDIO)、流式HTTP、无状态流式HTTP、SSE
Java MCP 服务端架构：
1.3.2 会话层（中层）
管控通信模式与连接状态：
- McpSession：会话管理核心接口
- McpClientSession：客户端专属会话实现
- McpServerSession：服务端专属会话实现
1.3.3 传输层（底层）
负责消息传输与序列化：
- McpTransport ：实现
JSON-RPC消息的序列化与反序列化 - 支持多种传输方案：标准输入输出(
STDIO)、HTTP/SSE、流式HTTP等 - 为上层所有通信能力提供底层支撑
2. Spring AI 集成 MCP
Spring AI 全面兼容 MCP，通过专属 Spring Boot 启动器与 MCP Java 注解提供完整能力，大幅降低开发门槛，助力搭建可无缝对接外部系统的高级 AI 应用。
Spring 开发者可参与 MCP 生态的两端开发：
- 构建调用
MCP服务端的AI应用 - 搭建
MCP服务端，将基于Spring开发的服务对外开放给整个AI生态。
2.1 客户端 Starters
包含：
spring-ai-starter-mcp-client：核心Starter，支持STDIO、基于Servlet的Streamable‑HTTP、无状态
Streamable‑HTTP、SSEspring-ai-starter-mcp-client-webflux：基于WebFlux的Streamable‑HTTP、无状态Streamable‑HTTP、SSE传输实现
2.2 服务端 Starters
标准输入输出（STDIO）：
| 服务器类型 | 依赖 | 配置属性 |
|---|---|---|
| 标准输入输出（STDIO） | spring-ai-starter-mcp-server | spring.ai.mcp.server.stdio=true |
WebMVC：
| 服务器类型 | 依赖 | 配置属性 |
|---|---|---|
| SSE WebMVC | spring-ai-starter-mcp-server-webmvc | spring.ai.mcp.server.protocol=SSE 或留空 |
| Streamable-HTTP WebMVC | spring-ai-starter-mcp-server-webmvc | spring.ai.mcp.server.protocol=STREAMABLE |
| Stateless Streamable-HTTP WebMVC | spring-ai-starter-mcp-server-webmvc | spring.ai.mcp.server.protocol=STATELESS |
WebMVC （响应式）:
| 服务器类型 | 依赖 | 配置属性 |
|---|---|---|
| SSE WebFlux | spring-ai-starter-mcp-server-webflux | spring.ai.mcp.server.protocol=SSE 或留空 |
| Streamable-HTTP WebFlux | spring-ai-starter-mcp-server-webflux | spring.ai.mcp.server.protocol=STREAMABLE |
| Stateless Streamable-HTTP WebFlux | spring-ai-starter-mcp-server-webflux | spring.ai.mcp.server.protocol=STATELESS |
2.3 MCP 注解
除代码编程方式外，Spring AI 提供注解模块 ，支持通过注解快速编写 MCP 客户端与服务端逻辑。该方案采用声明式编程模型，简化 MCP 功能的开发与注册。
核心能力：
- 通过简易注解快速创建
MCP工具、资源、提示词 - 以声明式方式处理客户端通知与请求
- 减少样板代码，提升项目可维护性
- 自动为工具参数生成
JSON结构定义 - 支持获取特殊参数与上下文信息
主要注解与组件：
- 服务端注解 ：
@McpTool、@McpResource、@McpPrompt、@McpComplete - 客户端注解 ：
@McpLogging、@McpSampling、@McpElicitation、@McpProgress - 特殊参数类 ：
McpSyncServerExchange、McpAsyncServerExchange、McpTransportContext、McpMeta - 自动扫描：支持注解扫描，可自定义扫描/排除指定包路径
- Spring Boot 适配 ：与
MCP启动器无缝结合