模型上下文协议（MCP）
初次使用 MCP？ 请从我们的 MCP 入门指南 开始，以快速了解基本概念并查看实操示例。
模型上下文协议（MCP）是一种标准化协议，旨在让 AI 模型以结构化的方式与外部工具和资源进行交互。可以将其视为 AI 模型与现实世界之间的桥梁——通过一致的接口，使模型能够访问数据库、API、文件系统及其他外部服务。它支持多种传输机制，以在不同环境中提供灵活性。
MCP Java SDK 提供了 Model Context Protocol 的 Java 实现，支持通过同步和异步通信模式与 AI 模型及工具进行标准化交互。
Spring AI 通过专用的 Boot Starters 和 MCP Java 注解提供对 MCP 的全面支持，使得构建能够无缝连接外部系统的复杂 AI 驱动应用比以往任何时候都更加简单。这意味着 Spring 开发者可以参与到 MCP 生态系统的两侧——构建消费 MCP 服务器的 AI 应用，以及创建向更广泛的 AI 社区暴露基于 Spring 的服务的 MCP 服务器。您可以使用 Spring Initializer 来启动具备 MCP 支持的 AI 应用。
MCP Java SDK 架构
本节概述了 MCP Java SDK 架构。有关 Spring AI MCP 集成，请参阅 Spring AI MCP Boot Starters 文档。
Java MCP 实现遵循三层架构，通过分离关注点以提升可维护性和灵活性：
图 1. MCP 堆叠架构
客户端/服务器层（顶层）
最上层负责主要的应用逻辑和协议操作：
-
McpClient - 管理客户端操作和服务器连接
-
McpServer - 处理服务器端协议操作和客户端请求
-
这两个组件都使用下方的会话层进行通信管理
会话层（中间）
中间层负责管理通信模式并维护连接状态：
-
McpSession - 核心会话管理接口
-
McpClientSession - 客户端特定会话实现
-
McpServerSession - 服务端特定会话实现
传输层（底层）
最底层负责实际的消息传输和序列化：
-
McpTransport - 管理 JSON-RPC 消息的序列化和反序列化
-
支持多种传输实现（STDIO、HTTP/SSE、Streamable-HTTP 等）
-
为所有更高层级的通信提供基础
| MCP Client | |
|---|---|
| MCP Client 是模型上下文协议 (MCP) 架构中的关键组件，负责建立和管理与 MCP 服务器的连接。它实现了协议的客户端部分，处理： - 协议版本协商，以确保与服务器兼容 - 能力协商，以确定可用功能 - 消息传输和 JSON-RPC 通信 - 工具发现和执行 - 资源访问和管理 - 提示系统交互 - 可选功能： - Roots 管理 - 采样 (Sampling) 支持 - 同步和异步操作 - 传输选项： - 基于 Stdio 的传输，用于基于进程的通信 - 基于 Java HttpClient 的 SSE 客户端传输 - WebFlux SSE 客户端传输，用于响应式 HTTP 流 |  |
| MCP Server | |
|---|---|
| MCP Server 是模型上下文协议（MCP）架构中的基础组件，向客户端提供工具、资源和能力。它实现了协议的服务器端部分，负责： - 服务器端协议操作实现 - 工具暴露与发现 - 基于 URI 的资源管理 - 提示模板（Prompt template）提供与处理 - 与客户端的能力协商 - 结构化日志与通知 - 并发客户端连接管理 - 同步与异步 API 支持 - 传输实现： - Stdio、Streamable-HTTP、Stateless Streamable-HTTP、SSE |  |
有关使用低层 MCP Client/Server API 的详细实现指南，请参阅 MCP Java SDK 文档。如需使用 Spring Boot 进行简化配置，请使用下文描述的 MCP Boot Starters。
Spring AI MCP 集成
Spring AI 通过以下 Spring Boot starter 提供 MCP 集成：
-
spring-ai-starter-mcp-client- 核心 Starter，提供STDIO、基于 Servlet 的Streamable-HTTP、Stateless Streamable-HTTP以及SSE支持 -
spring-ai-starter-mcp-client-webflux- 基于 WebFlux 的Streamable-HTTP、Stateless Streamable-HTTP和SSE传输实现
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 |
WebFlux（Reactive）
| 服务器类型 | 依赖项 | 属性 |
|---|---|---|
| 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 |
除了编程式 MCP 客户端和服务器配置外，Spring AI 还通过 MCP Annotations 模块为 MCP 服务器和客户端提供基于注解的方法处理。这种方法使用带有 Java 注解的清晰声明式编程模型，简化了 MCP 操作的创建和注册。
MCP 注解模块使开发者能够：
-
通过简单的注解创建 MCP 工具、资源和提示词
-
以声明式方式处理客户端通知和请求
-
减少样板代码并提高可维护性
-
自动为工具参数生成 JSON Schema
-
访问特殊参数和上下文信息
主要特性包括：
升级到 Spring AI 2.0
自 Spring AI 2.0 起，Spring 特有的 MCP 传输实现（mcp-spring-webflux 和 mcp-spring-webmvc）不再由 MCP Java SDK 提供，而是被移入了 Spring AI 项目本身。这是一个破坏性变更，要求直接引用这些传输工件或类的应用程序更新其依赖项和导入。
Maven 依赖 Group ID 变更
mcp-spring-webflux 和 mcp-spring-webmvc 构件已从 io.modelcontextprotocol.sdk 组迁移至 org.springframework.ai。
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webflux</artifactId>
</dependency>
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>mcp-spring-webflux</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
</dependency>
在使用 spring-ai-bom 或 Spring AI starter 依赖项（spring-ai-starter-mcp-server-webflux、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-client-webflux）时，无需指定显式版本号 —— BOM 会自动管理版本。
Java 软件包重定位
所有传输类已迁移至 org.springframework.ai 包。
表 1. 服务器传输类
| 类 | 旧包 (MCP SDK) | 新包 (Spring AI) |
|---|---|---|
WebFluxSseServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebFluxStreamableServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebFluxStatelessServerTransport | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webflux.transport |
WebMvcSseServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStreamableServerTransportProvider | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStatelessServerTransport | io.modelcontextprotocol.server.transport | org.springframework.ai.mcp.server.webmvc.transport |
表 2. 客户端传输类
| 类名称 | 旧包 (MCP SDK) | 新包 (Spring AI) |
|---|---|---|
WebFluxSseClientTransport | io.modelcontextprotocol.client.transport | org.springframework.ai.mcp.client.webflux.transport |
WebClientStreamableHttpTransport | io.modelcontextprotocol.client.transport | org.springframework.ai.mcp.client.webflux.transport |
// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;
MCP SDK 版本要求
Spring AI 2.0 要求 MCP Java SDK 1.0.0（RC1 或更高版本）。SDK 的版本已从 0.18.x 提升至 1.0.x 发布系列。请相应更新 BOM 或显式指定的版本。
Spring Boot 自动配置用户
如果您仅通过 Spring AI starters 完全依赖 Spring Boot 自动配置，则无需修改任何 Java 代码。自动配置内部已经更新以引用新的包。只需按照上述说明更新 pom.xml/build.gradle 中的依赖坐标即可。
更多资源
本节摘要
MCP Client 启动器
Spring AI MCP（模型上下文协议）客户端 Boot Starter 为 Spring Boot 应用提供 MCP 客户端功能的自动配置。它支持同步和异步客户端实现，并可选择多种传输方式。
MCP Server Boot Starters
3 个项目
MCP 安全（WIP）
Spring AI MCP 安全模块为 Spring AI 中的模型上下文协议（MCP）实现提供了全面的 OAuth 2.0 和基于 API Key 的安全支持。这个由社区驱动的项目使开发人员能够使用行业标准身份验证和授权机制来保护 MCP 服务器和客户端。
MCP 注解
4 个项目