模型上下文协议（MCP）

模型上下文协议（Model Context Protocol，MCP）是一种标准化协议，使 AI 模型能够以结构化的方式与外部工具和资源进行交互。可以将其理解为 AI 模型与现实世界之间的桥梁——通过一致的接口访问数据库、API、文件系统以及其他外部服务。MCP 支持多种传输机制，以适应不同环境的灵活需求。

MCP Java SDK 提供了 MCP 的 Java 实现，使得可以通过同步或异步通信模式，与 AI 模型和工具进行标准化交互。

Spring AI 对 MCP 提供了全面支持，包括专用的 Boot Starter 和 MCP Java 注解，让构建能够无缝连接外部系统的复杂 AI 应用变得更加容易。这意味着 Spring 开发者可以同时参与 MCP 生态的两个方面——既可以构建消费 MCP 服务器的 AI 应用，也可以创建向更广泛 AI 社区开放 Spring 服务的 MCP 服务器。可以通过 Spring Initializer 启动并快速集成 MCP 支持的 AI 应用。

MCP Java SDK 架构

Java 版 MCP 实现采用三层架构，以实现关注点分离，从而提高可维护性和灵活性：

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

最上层负责主要的应用逻辑和协议操作：

• McpClient —— 管理客户端操作和服务器连接
• McpServer —— 处理服务端的协议操作和客户端请求
• 这两个组件都利用下方的会话层来管理通信。

会话层（中间层）

中间层负责管理通信模式并维护连接状态：

• McpSession —— 核心会话管理接口
• McpClientSession —— 客户端专用会话实现
• McpServerSession —— 服务端专用会话实现

传输层（底层）

底层负责实际的消息传输和序列化：

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

MCP Client

MCP 客户端是 Model Context Protocol (MCP) 架构中的关键组件，负责与 MCP 服务器建立和管理连接。它实现了协议的客户端功能，主要处理以下事务：

• 协议版本协商，以确保与服务器的兼容性
• 功能能力协商，以确定可用特性
• 消息传输和 JSON-RPC 通信
• 工具发现与执行
• 资源访问与管理
• 提示系统交互
• 可选特性：
  • 根资源管理
  • 抽样支持
• 同步与异步操作
• 传输选项：
  • 基于 Stdio 的进程通信传输
  • 基于 Java HttpClient 的 SSE 客户端传输
  • 基于 WebFlux 的 SSE 客户端传输，用于响应式 HTTP 流式处理

MCP Server

MCP 服务器是 Model Context Protocol (MCP) 架构中的基础组件，为客户端提供工具、资源和功能。它实现了协议的服务端功能，主要负责：

• 服务端协议操作的实现
  • 工具的暴露与发现
  • 基于 URI 的资源管理
  • 提示模板的提供与处理
  • 与客户端的功能能力协商
  • 结构化日志记录与通知
• 并发客户端连接管理
• 同步与异步 API 支持
• 传输实现方式：
  • Stdio，Streamable-HTTP，Stateless Streamable-HTTP，SSE

有关使用底层 MCP 客户端/服务器 API 的详细实现指南，请参考 MCP Java SDK 文档。若希望简化配置，可使用下文介绍的 Spring Boot MCP 启动器（Boot Starters）。

Spring AI MCP 集成

Spring AI 通过以下 Spring Boot 启动器（Starters）提供 MCP 集成：

客户端启动器

• spring-ai-starter-mcp-client：核心启动器，提供 STDIO、基于 Servlet 的可流式 HTTP（Streamable-HTTP）、无状态可流式 HTTP（Stateless Streamable-HTTP）以及 SSE 支持。
• spring-ai-starter-mcp-client-webflux：基于 WebFlux 的可流式 HTTP、无状态可流式 HTTP 及 SSE 传输实现。

服务器启动器

STDIO

WebMVC

WebMVC（Reactive）

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 Starters 无缝集成

附加资源

• MCP 注解文档
• MCP 客户端 Boot Starters 文档
• MCP 服务器 Boot Starters 文档
• MCP 工具类文档
• 模型上下文协议（MCP）规范