Spring AI

参考文档

模型上下文协议（MCP）

模型上下文协议（MCP）

初次接触 MCP？请从我们的《MCP 入门指南》开始，获取快速介绍和动手示例。

模型上下文协议（Model Context Protocol，MCP）是一种标准化协议，使 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、SSE

在这里插入图片描述

Java MCP 服务器架构图

有关使用底层 MCP 客户端/服务端 API 的详细实现指导，请参阅 MCP Java SDK 文档。如需使用 Spring Boot 简化设置，请使用下述 MCP Boot Starter。

Spring AI MCP 集成

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

客户端 Starter

Starter 说明
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 传输实现

服务端 Starter

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

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

<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

导入更新示例

// 之前
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// 之后
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 Starter 依赖 Spring Boot 自动配置，则无需更改任何 Java 代码。自动配置已在内部更新以引用新包。只需按照上述描述更新 pom.xml/build.gradle 中的依赖坐标即可。

其他资源

  • MCP 注解文档
  • MCP 客户端 Boot Starter 文档
  • MCP 服务端 Boot Starter 文档
  • MCP 工具类文档
  • 模型上下文协议规范
# spring # 人工智能 # java
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

周末速报：AI圈大事盘点

avatar MCP技术社区

从大模型到自主智能：开发者必看的 AI Agent 全栈技术指南

当前AI Agent生态已形成标准化分层架构，主要包括六大核心组件：基础模型层（如Llama、GPT系列）作为"大脑"负责推理；数据存储层（Weaviate、Pinecone）构建知识库；开发框架层（LangChain、AutoGen）提供工作流编排；工具执行层（Composio）实现外部系统交互；记忆管理层（Mem0）处理状态持久化；可观测性工具（Langfuse）保障系统监控。掌握这一技术栈将

avatar MCP技术社区

DBLens数据库管理和开发工具

完成上述配置后，你的企业微信里就多了一个「数据库 Agent」。团队成员可以像问一个懂数据的同事一样，用自然语言快速获取信息。一句话总结：把 DBLens 的 LensAI Agent 接入企微机器人，让数据查询从「提需求 → 等排期 → 截图」变成「直接问 → 秒回」。

avatar MCP技术社区