Spring AI MCP实践指南：通过MCP连接你的应用与AI大模型_mcpsyncclient

技术文档

Spring AI MCP实践指南：通过MCP连接你的应用与AI大模型

随着人工智能技术的快速发展，如何将AI能力无缝集成到现有应用中成为开发者面临的重要挑战。Spring AI提供了强大的框架来简化AI集成过程，而Model Context Protocol (MCP)则为AI模型与外部工具交互提供了标准化协议。本文将深入探讨Spring AI与MCP的结合实践，帮助开发者构建功能强大的AI增强型应用。

一、MCP简介

Model Context Protocol (MCP)是一种标准化协议，使AI模型能够以结构化方式与外部工具和资源进行交互。它为大语言模型(LLM)提供了与外部世界交互的标准接口，支持多种传输机制，为不同环境提供灵活性。

MCP的核心功能：

工具调用：允许AI模型发现并执行外部工具
资源访问：通过标准化URI模板访问外部资源
提示管理：处理提示模板和参数化提示内容
文件系统访问：通过根目录限制安全访问文件系统
结构化日志：提供标准化的日志记录机制

MCP通过多层架构实现，包括客户端/服务端层、会话层和传输层，确保消息的可靠传递和处理。它支持同步和异步通信模式，适用于各种应用场景。

二、Spring AI简介

Spring AI是Spring生态系统的最新成员，专注于简化AI工程的应用框架。它将Spring生态系统的设计原则（如可移植性和模块化设计）应用到AI领域，促进使用POJO（普通Java对象）作为应用构建块。

Spring AI的主要特点：

支持多种AI模型提供商：包括Anthropic、OpenAI、Microsoft、Amazon、Google和Ollama等，支持文本生成、嵌入、图像生成、音频处理等多种模型类型。
可移植API：跨AI提供商的统一API，支持同步和流式API选项。
结构化输出：将AI模型输出映射到Java对象。
向量数据库支持：支持多种向量数据库提供商。
工具/函数调用：允许模型请求执行客户端工具和函数。
可观测性：提供AI相关操作的洞察。
文档注入ETL框架：用于数据工程。
AI模型评估：帮助评估生成内容并防止幻觉响应。
ChatClient API：用于与AI聊天模型通信的流畅API。
Spring Boot自动配置：所有AI模型和向量存储的自动配置和启动器。

Spring AI MCP则是Spring AI生态系统的一部分，它扩展了MCP Java SDK，提供Spring Boot集成，包括客户端和服务器启动器，大大简化了MCP应用的开发。

三、MCP中SSE和stdio的区别

MCP支持两种主要的传输机制：SSE（Server-Sent Events）和stdio（标准输入/输出）。这两种机制各有优缺点，适用于不同的场景。

SSE（Server-Sent Events）

SSE是一种基于HTTP的单向通信技术，允许服务器向客户端推送数据。在MCP中，SSE传输主要用于分布式系统，支持远程访问和多客户端连接。

SSE的特点：

基于HTTP：利用标准HTTP协议，无需特殊端口或协议。
远程通信：支持不同物理机器之间的通信。
多客户端支持：可以同时服务多个客户端。
可扩展性：适合分布式系统和云部署场景。
安全性：可以利用HTTPS等标准安全机制。

SSE的适用场景：

分布式系统架构
需要远程访问的应用
微服务之间的通信
多用户同时访问的系统
云部署环境

stdio（标准输入/输出）

stdio是一种进程内通信机制，通过标准输入和输出流进行数据传输。在MCP中，stdio传输主要用于本地集成，提供低延迟和简单的设置。

stdio的特点：

进程内通信：直接通过进程的标准输入/输出流进行通信。
低延迟：没有网络开销，响应更快。
简单设置：无需配置网络端点或处理网络问题。
单一客户端：通常用于一对一的客户端-服务器通信。
本地执行：客户端和服务器在同一台机器上运行。

stdio的适用场景：

本地集成
单用户应用程序
命令行工具
需要低延迟的应用
开发和测试环境

二者详细对比

| 特性 | SSE | stdio |

|------|-----|-------|

| 通信方式 | 基于HTTP的单向通信 | 进程内标准输入/输出流 |

| 网络依赖 | 需要网络连接 | 不依赖网络 |

| 延迟 | 较高（受网络影响） | 较低（进程内通信） |

| 客户端数量 | 支持多客户端 | 通常单一客户端 |

| 部署复杂性 | 需要配置HTTP端点 | 简单，无需特殊配置 |

| 安全性考虑 | 需要考虑HTTP安全性 | 主要关注进程安全性 |

| 集成方式 | 远程服务集成 | 本地工具集成 |

| 扩展性 | 高（可以横向扩展） | 低（受限于本地资源） |

| 适用环境 | 分布式系统、微服务 | 本地应用、命令行工具 |

在Spring AI MCP中，可以根据应用需求选择适合的传输机制。对于需要远程访问的服务，SSE是更好的选择；而对于本地集成和低延迟要求的场景，stdio则更为合适。

四、Spring AI MCP实现示例

下面我们将通过实际代码示例，分别展示如何使用Spring AI MCP实现SSE和stdio两种传输方式。

4.1 环境准备

首先，我们需要添加Spring AI MCP相关依赖到项目中：

 org.springframework.boot spring-boot-starter-parent 3.2.0   org.springframework.ai spring-ai-starter-mcp-client 1.0.0    org.springframework.ai spring-ai-starter-mcp-client-webflux 1.0.0    org.springframework.boot spring-boot-starter-web    org.springframework.boot spring-boot-starter-webflux

4.2 SSE实现示例

4.2.1 配置SSE客户端

在application.yml中配置SSE客户端：

spring: ai: mcp: client: enabled: true name: mcp-sse-client version: 1.0.0 request-timeout: 30s type: SYNC # 同步客户端，也可以设为ASYNC使用异步客户端 sse: connections: server1:  url: http://localhost:8080/mcp/message

4.2.2 SSE客户端实现

import org.springframework.ai.mcp.client.McpSyncClient;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.CommandLineRunner;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import java.util.List;import java.util.Map;@SpringBootApplicationpublic class SseClientApplication { public static void main(String[] args) { SpringApplication.run(SseClientApplication.class, args); } @Autowired private List mcpSyncClients; @Bean public CommandLineRunner runner() { return args -> { // 假设我们只有一个客户端配置 McpSyncClient client = mcpSyncClients.get(0); // 初始化客户端连接 client.initialize(); // 列出可用工具 var tools = client.listTools(); System.out.println(\"可用工具: \" + tools.getTools()); // 调用一个名为\"calculator\"的工具 var result = client.callTool( new CallToolRequest(\"calculator\",  Map.of(\"operation\", \"add\", \"a\", 2, \"b\", 3)) ); System.out.println(\"计算结果: \" + result.getResult()); // 列出可用资源 var resources = client.listResources(); System.out.println(\"可用资源: \" + resources.getResources()); // 关闭客户端 client.closeGracefully(); }; }}

4.2.3 SSE服务端实现

import org.springframework.ai.mcp.schema.Tool;import org.springframework.ai.mcp.server.McpServer;import org.springframework.ai.mcp.server.McpSyncServer;import org.springframework.ai.mcp.server.feature.McpServerFeatures;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import org.springframework.web.servlet.config.annotation.EnableWebMvc;import java.util.Map;@SpringBootApplication@EnableWebMvcpublic class SseServerApplication { public static void main(String[] args) { SpringApplication.run(SseServerApplication.class, args); } @Bean public WebMvcSseServerTransport webMvcSseServerTransport(ObjectMapper mapper) { return new WebMvcSseServerTransport(mapper, \"/mcp/message\"); } @Bean public RouterFunction mcpRouterFunction(WebMvcSseServerTransport transport) { return transport.getRouterFunction(); } @Bean public McpSyncServer mcpSyncServer(WebMvcSseServerTransport transport) { // 创建一个简单的计算器工具 var calculatorTool = new Tool( \"calculator\", \"基础计算器\", Map.of( \"operation\", \"string\", \"a\", \"number\", \"b\", \"number\" ) ); // 工具处理函数 var calculatorHandler = (Map args) -> { String operation = (String) args.get(\"operation\"); Number a = (Number) args.get(\"a\"); Number b = (Number) args.get(\"b\"); double result = 0; switch (operation) { case \"add\":  result = a.doubleValue() + b.doubleValue();  break; case \"subtract\":  result = a.doubleValue() - b.doubleValue();  break; case \"multiply\":  result = a.doubleValue() * b.doubleValue();  break; case \"divide\":  result = a.doubleValue() / b.doubleValue();  break; } return new CallToolResult(result, false); }; // 创建和配置服务器 return McpServer.sync(transport) .serverInfo(\"calculator-server\", \"1.0.0\") .capabilities(ServerCapabilities.builder() .tools(true) // 启用工具支持 .logging() // 启用日志支持 .build()) .tools(new McpServerFeatures.SyncToolRegistration(calculatorTool, calculatorHandler)) .build(); }}

4.3 stdio实现示例

4.3.1 配置stdio客户端

在application.yml中配置stdio客户端：

spring: ai: mcp: client: enabled: true name: mcp-stdio-client version: 1.0.0 request-timeout: 30s type: SYNC stdio: connections: calculatorServer:  command: java  args: - -jar - calculator-server.jar  env: DEBUG: \"true\"

也可以使用Claude Desktop格式的JSON配置文件：

spring: ai: mcp: client: stdio: servers-configuration: classpath:mcp-servers.json

mcp-servers.json示例：

{ \"mcpServers\": { \"calculator\": { \"command\": \"java\", \"args\": [ \"-jar\", \"calculator-server.jar\" ], \"env\": { \"DEBUG\": \"true\" } } }}

4.3.2 stdio客户端实现

import org.springframework.ai.mcp.client.McpSyncClient;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.CommandLineRunner;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import java.util.List;import java.util.Map;@SpringBootApplicationpublic class StdioClientApplication { public static void main(String[] args) { SpringApplication.run(StdioClientApplication.class, args); } @Autowired private List mcpSyncClients; @Bean public CommandLineRunner runner() { return args -> { // 获取名为\"calculatorServer\"的客户端 McpSyncClient client = mcpSyncClients.stream() .filter(c -> c.getName().equals(\"calculatorServer\")) .findFirst() .orElseThrow(() -> new RuntimeException(\"未找到calculatorServer客户端\")); // 初始化客户端连接 client.initialize(); // 列出可用工具 var tools = client.listTools(); System.out.println(\"可用工具: \" + tools.getTools()); // 调用计算器工具 var result = client.callTool( new CallToolRequest(\"calculator\",  Map.of(\"operation\", \"multiply\", \"a\", 10, \"b\", 5)) ); System.out.println(\"计算结果: \" + result.getResult()); // 应该输出50 // 关闭客户端 client.closeGracefully(); }; }}

4.3.3 stdio服务端实现

standalone-calculator-server.jar的主类：

import org.springframework.ai.mcp.schema.Tool;import org.springframework.ai.mcp.server.McpServer;import org.springframework.ai.mcp.server.McpSyncServer;import org.springframework.ai.mcp.server.feature.McpServerFeatures;import org.springframework.ai.mcp.transport.StdioServerTransport;import org.springframework.boot.CommandLineRunner;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import java.util.Map;@SpringBootApplicationpublic class StdioServerApplication { public static void main(String[] args) { SpringApplication.run(StdioServerApplication.class, args); } @Bean public CommandLineRunner runServer() { return args -> { // 创建stdio传输 StdioServerTransport transport = new StdioServerTransport(new ObjectMapper()); // 创建计算器工具 var calculatorTool = new Tool( \"calculator\",  \"基础计算器\",  Map.of(  \"operation\", \"string\",  \"a\", \"number\",  \"b\", \"number\" ) ); // 工具处理函数 var calculatorHandler = (Map args) -> { String operation = (String) args.get(\"operation\"); Number a = (Number) args.get(\"a\"); Number b = (Number) args.get(\"b\"); double result = 0; switch (operation) {  case \"add\": result = a.doubleValue() + b.doubleValue(); break;  case \"subtract\": result = a.doubleValue() - b.doubleValue(); break;  case \"multiply\": result = a.doubleValue() * b.doubleValue(); break;  case \"divide\": result = a.doubleValue() / b.doubleValue(); break; } return new CallToolResult(result, false); }; // 创建和配置服务器 McpSyncServer server = McpServer.sync(transport) .serverInfo(\"calculator-server\", \"1.0.0\") .capabilities(ServerCapabilities.builder()  .tools(true)  .logging()  .build()) .tools(new McpServerFeatures.SyncToolRegistration(calculatorTool, calculatorHandler)) .build(); // 服务器将通过stdio与客户端通信，直到进程终止 System.out.println(\"计算器服务器已启动，等待通过stdio接收命令...\"); }; }}

4.4 客户端自定义配置

可以通过实现McpSyncClientCustomizer或McpAsyncClientCustomizer接口来自定义客户端行为：

import org.springframework.ai.mcp.client.customizer.McpSyncClientCustomizer;import org.springframework.ai.mcp.client.McpClient;import org.springframework.stereotype.Component;import java.time.Duration;import java.util.List;@Componentpublic class CustomMcpClientConfig implements McpSyncClientCustomizer { @Override public void customize(String serverConfigurationName, McpClient.SyncSpec spec) { // 自定义请求超时时间 spec.requestTimeout(Duration.ofSeconds(30)); // 设置工具变更通知处理器 spec.toolsChangeConsumer((List tools) -> { System.out.println(\"工具列表已更新: \" + tools); }); // 设置日志处理器 spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> { System.out.println(\"[\" + log.getLevel() + \"] \" + log.getData()); }); }}

4.5 完整的异步WebFlux示例

下面是一个使用WebFlux实现的异步MCP客户端和服务器的完整示例：

4.5.1 异步WebFlux客户端

import org.springframework.ai.mcp.client.McpAsyncClient;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.CommandLineRunner;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import reactor.core.publisher.Mono;import java.util.List;import java.util.Map;@SpringBootApplicationpublic class AsyncWebFluxClientApplication { public static void main(String[] args) { SpringApplication.run(AsyncWebFluxClientApplication.class, args); } @Autowired private List mcpAsyncClients; @Bean public CommandLineRunner runner() { return args -> { // 获取第一个客户端 McpAsyncClient client = mcpAsyncClients.get(0); // 使用响应式编程方式与MCP服务器交互 client.initialize() .flatMap(initResult -> {  System.out.println(\"客户端初始化成功\");  return client.listTools(); }) .flatMap(tools -> {  System.out.println(\"可用工具: \" + tools.getTools());  // 调用计算器工具  return client.callTool(new CallToolRequest( \"calculator\", Map.of(\"operation\", \"add\", \"a\", 5, \"b\", 3)  )); }) .flatMap(result -> {  System.out.println(\"计算结果: \" + result.getResult());  return Mono.just(\"完成\"); }) .doFinally(signalType -> {  // 关闭客户端  client.closeGracefully().subscribe(); }) .subscribe(); }; }}

配置文件 application.yml:

spring: ai: mcp: client: enabled: true name: webflux-mcp-client version: 1.0.0 request-timeout: 30s type: ASYNC # 异步客户端 sse: connections: webfluxServer:  url: http://localhost:8080/mcp/message

4.5.2 异步WebFlux服务器

import org.springframework.ai.mcp.schema.Tool;import org.springframework.ai.mcp.server.McpAsyncServer;import org.springframework.ai.mcp.server.McpServer;import org.springframework.ai.mcp.server.feature.McpServerFeatures;import org.springframework.ai.mcp.transport.webflux.WebFluxSseServerTransport;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import org.springframework.web.reactive.function.server.RouterFunction;import reactor.core.publisher.Mono;import java.util.Map;@SpringBootApplicationpublic class AsyncWebFluxServerApplication { public static void main(String[] args) { SpringApplication.run(AsyncWebFluxServerApplication.class, args); } @Bean public WebFluxSseServerTransport webFluxSseServerTransport(ObjectMapper mapper) { return new WebFluxSseServerTransport(mapper, \"/mcp/message\"); } @Bean public RouterFunction mcpRouterFunction(WebFluxSseServerTransport transport) { return transport.getRouterFunction(); } @Bean public McpAsyncServer mcpAsyncServer(WebFluxSseServerTransport transport) { // 创建计算器工具 var calculatorTool = new Tool( \"calculator\", \"基础计算器\", Map.of( \"operation\", \"string\", \"a\", \"number\", \"b\", \"number\" ) ); // 异步工具处理函数 var calculatorHandler = (Map args) -> { String operation = (String) args.get(\"operation\"); Number a = (Number) args.get(\"a\"); Number b = (Number) args.get(\"b\"); double result = 0; switch (operation) { case \"add\":  result = a.doubleValue() + b.doubleValue();  break; case \"subtract\":  result = a.doubleValue() - b.doubleValue();  break; case \"multiply\":  result = a.doubleValue() * b.doubleValue();  break; case \"divide\":  result = a.doubleValue() / b.doubleValue();  break; } // 使用Mono包装结果 return Mono.just(new CallToolResult(result, false)); }; // 创建和配置异步服务器 return McpServer.async(transport) .serverInfo(\"calculator-server\", \"1.0.0\") .capabilities(ServerCapabilities.builder() .tools(true) .logging() .build()) .tools(new McpServerFeatures.AsyncToolRegistration(calculatorTool, calculatorHandler)) .build(); }}

五、最佳实践与建议

在使用Spring AI MCP进行开发时，以下是一些最佳实践和建议：

5.1 选择合适的传输机制

如果应用需要远程访问或分布式架构，选择SSE传输
对于本地集成和低延迟要求，选择stdio传输
使用WebFlux实现可以提供更好的可扩展性和响应式编程模型

5.2 客户端配置建议

合理设置请求超时时间，避免长时间阻塞
使用客户端自定义器（Customizer）根据需求调整客户端行为
为生产环境推荐使用WebFlux-based SSE实现
使用异步客户端处理高并发场景

5.3 服务端设计考虑

工具设计应该简单明确，便于AI模型理解和使用
提供详细的工具描述和参数说明
实现适当的错误处理机制，返回有意义的错误信息
使用结构化日志记录系统状态和调试信息

5.4 安全性考虑

限制文件系统访问范围，仅公开必要的根目录
对敏感操作实施适当的权限检查
使用HTTPS保护SSE通信
记录和监控工具调用，防止异常使用

5.5 性能优化

对频繁使用的工具进行缓存
使用异步API处理长时间运行的操作
合理设置连接池大小（对于SSE实现）
考虑使用WebFlux实现提高吞吐量

六、总结

Spring AI MCP为开发者提供了一个强大的框架，用于构建与AI模型交互的应用。通过标准化的协议和灵活的传输机制，它简化了AI能力的集成过程。本文详细介绍了MCP的核心概念、Spring AI的主要特点，以及SSE和stdio两种传输机制的区别和实现。通过具体的代码示例，展示了如何使用Spring AI MCP构建同步和异步客户端/服务器应用。

随着AI技术的不断发展，MCP将在连接AI模型与外部世界方面发挥越来越重要的作用。Spring AI MCP作为Java生态系统中的重要工具，为开发者提供了便捷的方式来构建智能化应用，实现AI能力的无缝集成。

通过合理选择传输机制和遵循最佳实践，开发者可以充分发挥Spring AI MCP的潜力，构建功能强大、性能卓越的AI增强型应用。

Spring AI MCP实践指南：通过MCP连接你的应用与AI大模型_mcpsyncclient