BytesRouter

主题

Spring AI 文档版本 2.1.0-SNAPSHOT 源快照 1f368acd 更新于 2026-10-16

Model Context Protocol (MCP)

TIP

初识 MCP？ 从我们的 MCP 入门 指南开始，获得快速介绍与上手示例。

Model Context Protocol（MCP）是一种标准化协议，使 AI 模型能够以结构化的方式与外部工具及资源交互。 把它想象成你的 AI 模型与现实世界之间的一座桥——让它们能通过一致的接口访问数据库、API、文件系统和其他外部服务。 它支持多种传输机制，以在不同环境之间提供灵活性。

MCP Java SDK 提供了 Model Context Protocol 的 Java 实现，通过同步与异步两种通信模式，实现对 AI 模型与工具的标准化交互。

Spring AI 通过专用的 Boot Starters 和 MCP Java 注解全面拥抱 MCP，让构建能无缝连接外部系统的精巧 AI 应用变得前所未有的简单。 这意味着 Spring 开发者可以参与到 MCP 生态的两侧——既构建消费 MCP 服务端的 AI 应用，也创建把基于 Spring 的服务暴露给更广泛 AI 社区的 MCP 服务端。 使用 Spring Initializer 为你的 AI 应用带 MCP 支持搭脚手架。

MCP Java SDK 架构

TIP

本节概述 MCP Java SDK 架构。

关于 Spring AI 的 MCP 集成，请参阅 Spring AI MCP Boot Starters 文档。

Java 的 MCP 实现遵循三层架构，为了可维护性与灵活性而分离关注点：

.MCP 栈架构

客户端/服务端层（顶层）

顶层处理主要的应用逻辑与协议操作：

  • McpClient - 管理客户端操作与服务端连接
  • McpServer - 处理服务端协议操作与客户端请求
  • 两个组件都利用下面的会话层进行通信管理

会话层（中层）

中层管理通信模式并维持连接状态：

  • McpSession - 核心会话管理接口
  • McpClientSession - 客户端特定的会话实现
  • McpServerSession - 服务端特定的会话实现

传输层（底层）

底层处理实际的消息传输与序列化：

  • McpTransport - 管理 JSON-RPC 消息的序列化与反序列化
  • 支持多种传输实现（STDIO、HTTP/SSE、Streamable-HTTP 等）
  • 为所有高层通信提供基础

| MCP Client a| MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责建立并管理与 MCP 服务端的连接。它实现协议的客户端侧，处理： * 协议版本协商，确保与服务端兼容 * 能力协商，确定可用特性 * 消息传输与 JSON-RPC 通信 * 工具的发现与执行 * 资源的访问与管理 * 与 prompt 系统的交互 * 可选特性: ** Roots 管理 ** Sampling 支持 * 同步与异步操作 * 传输方式选项: ** 基于 stdio 的进程间通信传输 ** 基于 Java HttpClient 的 SSE 客户端传输 ** 用于响应式 HTTP 流式的 WebFlux SSE 客户端传输 ^a| image::mcp/java-mcp-client-architecture.jpg[Java MCP Client Architecture, width=500] | ---

| MCP Server a| MCP 服务端是模型上下文协议（MCP）架构中的基础组件，向客户端提供工具、资源与能力。它实现协议的服务端侧，负责： * 服务端协议操作的实现 ** 工具的暴露与发现 ** 基于 URI 的资源管理与访问 ** prompt 模板的提供与处理 ** 与客户端的能力协商 ** 结构化日志与通知 * 并发客户端连接管理 * 同步与异步 API 支持 * 传输实现: ** Stdio、Streamable-HTTP、无状态 Streamable-HTTP、SSE ^a| image::mcp/java-mcp-server-architecture.jpg[Java MCP Server Architecture, width=600] | ---

关于使用底层 MCP 客户端/服务端 API 的详细实现指导，请参阅 MCP Java SDK 文档。 要借助 Spring Boot 简化装配，请使用下文所述的 MCP Boot Starters。

Spring AI MCP 集成

Spring AI 通过以下 Spring Boot starters 提供 MCP 集成：

客户端 Starters

  • spring-ai-starter-mcp-client - 提供 STDIO、基于 Servlet 的 Streamable-HTTP、Stateless Streamable-HTTP 与 SSE 支持的核心 starter
  • spring-ai-starter-mcp-client-webflux - 基于 WebFlux 的 Streamable-HTTP、Stateless Streamable-HTTP 与 SSE 传输实现

服务端 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
无状态 Streamable-HTTP WebMVC
spring-ai-starter-mcp-server-webmvc
spring.ai.mcp.server.protocol=STATELESS

WebFlux（响应式）

服务端类型
依赖
属性
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
无状态 Streamable-HTTP WebFlux
spring-ai-starter-mcp-server-webflux
spring.ai.mcp.server.protocol=STATELESS

Spring AI MCP 注解

除了程序化的 MCP 客户端与服务端配置之外，Spring AI 还通过 MCP 注解 模块，为 MCP 服务端和客户端提供基于注解的方法处理。 这种方法借助一种使用 Java 注解、简洁而声明式的编程模型，简化了 MCP 操作的创建与注册。

MCP 注解模块使开发者能够：

  • 使用简单的注解创建 MCP 工具、资源和提示词
  • 声明式地处理客户端侧的通知与请求
  • 减少样板代码并提升可维护性
  • 自动生成工具参数的 JSON 模式
  • 访问特殊参数与上下文信息

主要特性包括：

  • 服务端注解：@McpTool、@McpResource、@McpPrompt、@McpComplete
  • 客户端注解：@McpLogging、@McpSampling、@McpElicitation、@McpProgress
  • 特殊参数：McpSyncServerExchange、McpAsyncServerExchange、McpTransportContext、McpMeta
  • 自动发现：带可配置包包含/排除的注解扫描
  • Spring Boot 集成：与 MCP Boot Starters 无缝集成

升级到 Spring AI 2.0

从 Spring AI 2.0 起，Spring 特定的 MCP 传输实现（mcp-spring-webflux 和 mcp-spring-webmvc）不再由 MCP Java SDK 提供。它们已被移入 Spring AI 项目本身。这是一个破坏性变更，对于那些直接引用这些传输构件或类的应用，需要更新依赖与 import。

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.x）

xml
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

.变更后（MCP Java SDK >= 1.0.x 且 Spring AI >= 2.0.x）

xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

NOTE

当你使用 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 包中。

.服务端传输类

类
旧包（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

.客户端传输类

类
旧包（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

.import 更新示例

java
// 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 依赖坐标。

其他资源

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可