Spring AI参考文档模型上下文协议MCP模型上下文协议MCP初次接触 MCP请从我们的《MCP 入门指南》开始获取快速介绍和动手示例。模型上下文协议Model Context ProtocolMCP是一种标准化协议使 AI 模型能够以结构化方式与外部工具和资源进行交互。可以将其视为 AI 模型与现实世界之间的桥梁——通过一致的接口允许它们访问数据库、API、文件系统和其他外部服务。它支持多种传输机制以在不同环境中提供灵活性。MCP Java SDK 提供了模型上下文协议的 Java 实现通过同步和异步通信模式支持与 AI 模型和工具的标准化交互。Spring AI 通过专用的 Boot Starter 和 MCP Java 注解为 MCP 提供全面支持使得构建能够无缝连接到外部系统的复杂 AI 驱动应用程序变得更加容易。这意味着 Spring 开发者可以参与 MCP 生态系统的两端——既构建消费 MCP 服务器的 AI 应用程序也创建将基于 Spring 的服务暴露给更广泛 AI 社区的 MCP 服务器。使用 Spring Initializer 引导你的 AI 应用程序获得 MCP 支持。MCP Java SDK 架构本节概述 MCP Java SDK 架构。有关 Spring AI MCP 集成请参阅 Spring AI MCP Boot Starter 文档。Java MCP 实现遵循三层架构分离关注点以提高可维护性和灵活性MCP 堆栈架构图 1. MCP 堆栈架构客户端/服务端层顶层顶层处理主要的应用逻辑和协议操作McpClient—— 管理客户端操作和服务器连接McpServer—— 处理服务端协议操作和客户端请求两者均利用下层的会话层进行通信管理。会话层中间层中间层管理通信模式并维护连接状态McpSession—— 核心会话管理接口McpClientSession—— 客户端专用会话实现McpServerSession—— 服务端专用会话实现传输层底层底层处理实际的消息传输和序列化McpTransport—— 管理 JSON-RPC 消息的序列化与反序列化支持多种传输实现STDIO、HTTP/SSE、Streamable-HTTP 等为所有更高级别的通信提供基础MCP 客户端MCP 客户端是模型上下文协议架构中的关键组件负责建立和管理与 MCP 服务器的连接。它实现协议客户端侧的功能处理协议版本协商确保与服务器的兼容性能力协商确定可用功能消息传输和 JSON-RPC 通信工具发现和执行资源访问和管理提示词系统交互可选功能根Roots管理采样Sampling支持同步和异步操作传输选项基于 STDIO 的传输适用于基于进程的通信基于 Java HttpClient 的 SSE 客户端传输基于 WebFlux SSE 的客户端传输适用于响应式 HTTP 流式传输Java MCP 客户端架构图MCP 服务器MCP 服务器是模型上下文协议架构中的基础组件向客户端提供工具、资源和能力。它实现协议服务端侧的功能负责服务端协议操作的实现工具暴露和发现基于 URI 的资源访问管理提示词模板的提供和处理与客户端的能力协商结构化日志和通知并发客户端连接管理同步和异步 API 支持传输实现STDIO、Streamable-HTTP、无状态 Streamable-HTTP、SSEJava MCP 服务器架构图有关使用底层 MCP 客户端/服务端 API 的详细实现指导请参阅 MCP Java SDK 文档。如需使用 Spring Boot 简化设置请使用下述 MCP Boot Starter。Spring AI MCP 集成Spring AI 通过以下 Spring Boot Starter 提供 MCP 集成客户端 StarterStarter说明spring-ai-starter-mcp-client核心 Starter提供 STDIO、基于 Servlet 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 支持spring-ai-starter-mcp-client-webflux基于 WebFlux 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 传输实现服务端 StarterSTDIO服务器类型依赖属性标准输入/输出STDIOspring-ai-starter-mcp-serverspring.ai.mcp.server.stdiotrueWebMVC服务器类型依赖属性SSE WebMVCspring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocolSSE 或留空Streamable-HTTP WebMVCspring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocolSTREAMABLE无状态 Streamable-HTTP WebMVCspring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocolSTATELESSWebFlux响应式服务器类型依赖属性SSE WebFluxspring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocolSSE 或留空Streamable-HTTP WebFluxspring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocolSTREAMABLE无状态 Streamable-HTTP WebFluxspring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocolSTATELESSSpring AI MCP 注解除了编程式的 MCP 客户端和服务器配置外Spring AI 还通过 MCP 注解模块为 MCP 服务器和客户端提供基于注解的方法处理。这种方式使用简洁、声明式的编程模型和 Java 注解简化了 MCP 操作的创建和注册。MCP 注解模块使开发者能够使用简洁的注解创建 MCP 工具、资源和提示词以声明方式处理客户端通知和请求减少样板代码提高可维护性自动生成工具参数的 JSON Schema访问特殊参数和上下文信息主要特性包括服务端注解McpTool、McpResource、McpPrompt、McpComplete客户端注解McpLogging、McpSampling、McpElicitation、McpProgress特殊参数McpSyncServerExchange、McpAsyncServerExchange、McpTransportContext、McpMeta自动发现支持包包含/排除配置的注解扫描Spring Boot 集成与 MCP Boot Starter 无缝集成升级到 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。之前MCP Java SDK 1.0.x 且 Spring AI 2.0.xdependencygroupIdio.modelcontextprotocol.sdk/groupIdartifactIdmcp-spring-webflux/artifactId/dependencydependencygroupIdio.modelcontextprotocol.sdk/groupIdartifactIdmcp-spring-webmvc/artifactId/dependency之后MCP Java SDK 1.0.x 且 Spring AI 2.0.xdependencygroupIdorg.springframework.ai/groupIdartifactIdmcp-spring-webflux/artifactId/dependencydependencygroupIdorg.springframework.ai/groupIdartifactIdmcp-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 AIWebFluxSseServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transportWebFluxStreamableServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transportWebFluxStatelessServerTransportio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webflux.transportWebMvcSseServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transportWebMvcStreamableServerTransportProviderio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transportWebMvcStatelessServerTransportio.modelcontextprotocol.server.transportorg.springframework.ai.mcp.server.webmvc.transport表 2. 客户端传输类类旧包MCP SDK新包Spring AIWebFluxSseClientTransportio.modelcontextprotocol.client.transportorg.springframework.ai.mcp.client.webflux.transportWebClientStreamableHttpTransportio.modelcontextprotocol.client.transportorg.springframework.ai.mcp.client.webflux.transport导入更新示例// 之前importio.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;importio.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;importio.modelcontextprotocol.client.transport.WebFluxSseClientTransport;importio.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;// 之后importorg.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;importorg.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;importorg.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;importorg.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;MCP SDK 版本要求Spring AI 2.0 需要 MCP Java SDK 1.0.0RC1 或更高版本。SDK 版本已从 0.18.x 升级到 1.0.x 发布线。请相应更新你的 BOM 或显式版本。Spring Boot 自动配置用户如果你完全通过 Spring AI Starter 依赖 Spring Boot 自动配置则无需更改任何 Java 代码。自动配置已在内部更新以引用新包。只需按照上述描述更新pom.xml/build.gradle中的依赖坐标即可。其他资源MCP 注解文档MCP 客户端 Boot Starter 文档MCP 服务端 Boot Starter 文档MCP 工具类文档模型上下文协议规范