Spring AI 1.1.2 集成 MCP（Model Context Protocol）实战：以 Tavily 搜索为例

本文分享在 Spring Boot 3.5 + Spring AI 1.1.2 中集成 MCP Client 的完整落地方案。通过连接 Tavily MCP Server，让大模型在对话中自动调用搜索工具获取实时信息，同时保持 Spring Boot 体系内的工程化体验。

一、MCP 是什么？为什么需要它

MCP（Model Context Protocol） 是一种让 LLM 与外部工具/资源交互的标准化协议：

• MCP Server：将工具能力（搜索、查库、读文件等）以统一格式暴露
• MCP Client：连接 Server、拉取工具定义，并在需要时转发工具调用
• LLM（通过 Spring AI 的 tool-calling 能力）在对话过程中自动决定是否调用工具

在 Spring AI 1.1.2 之前，要给模型接外部工具需要手写 @Tool 或 FunctionCallback。MCP 的好处在于：你不需要自己写工具实现，直接复用社区已有的 MCP Server（数百个可用），配置即集成。

二、技术栈与版本

三、Maven 依赖配置

3.1 父工程：引入 Spring AI BOM 统一管理版本

在父 pom.xml 的 <properties> 中声明版本号：

<properties> <spring-ai.version>1.1.2</spring-ai.version> </properties> 

在 <dependencyManagement> 中引入 BOM，这样所有子模块无需重复写版本号：

<dependencyManagement> <dependencies> <!-- Spring AI BOM --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>${spring-ai.version}</version> <type>pom</type> <scope>import</scope> </dependency> ​ <!-- MCP Client Starter --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-client</artifactId> <version>${spring-ai.version}</version> </dependency> </dependencies> </dependencyManagement> 

3.2 AI 框架模块：引入所需依赖

我把 AI 相关能力封装在 framework-ai 模块中，核心依赖如下：

<dependencies> <!-- Spring AI - OpenAI Starter（兼容 OpenAI 协议的模型均可用） --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency> ​ <!-- Spring AI MCP Client Starter（关键！） --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-client</artifactId> </dependency> ​ <!-- WebFlux（用于流式输出） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> </dependencies> 

提示：spring-ai-starter-mcp-client 会自动引入 MCP 协议实现和 stdio/SSE 传输层，不需要额外依赖。

四、配置 MCP Client：stdio 方式连接 Tavily

MCP 支持多种传输方式（stdio、HTTP/SSE 等）。这里演示最常用的 stdio 模式——Spring 应用启动一个子进程，通过标准输入输出与 MCP Server 通信。

关于 Tavily：Tavily 是一个专为 AI 应用设计的搜索 API，每月提供 1000 次免费搜索额度，足够个人开发和小规模测试使用。前往 https://www.tavily.com/ 注册登录后即可获取 TAVILY_API_KEY。

在 application.yml（或对应 profile 配置）中添加：

spring: ai: openai: api-key: ${OPENAI_API_KEY} base-url: ${OPENAI_BASE_URL} embedding: options: model: ${OPENAI_EMBEDDING_MODEL} # MCP 客户端配置 mcp: client: type: SYNC # 同步模式（适配 Servlet 应用） request-timeout: 60s # 工具调用超时时间 initialized: true # 启动时初始化连接并拉取工具列表 stdio: connections: tavily: # 连接名称（可自定义） command: cmd.exe # Windows 下使用 cmd args: - /c - npx - -y - tavily-mcp@latest env: TAVILY_API_KEY: ${TAVILY_API_KEY} 

配置详解

**type: SYNC**Spring AI MCP Client 支持 SYNC 和 ASYNC 两种模式。如果你是传统 Servlet 应用（Spring MVC），选 SYNC；如果是全响应式应用（Spring WebFlux），选 ASYNC。

**initialized: true**启动时立即初始化 MCP 连接并拉取工具列表。如果设为 false，第一次调用时才会初始化，可能导致首次响应慢或"工具未生效"的问题。强烈建议设为 ​true。

**stdio.connections.tavily**定义一个名为 tavily 的 stdio 连接：

• command + args：拼起来就是 cmd.exe /c npx -y tavily-mcp@latest，即通过 npx 拉取并运行 tavily-mcp
• env：只注入到子进程的环境变量，API Key 不会暴露给模型

Linux/Mac 用户：将 command 改为 npx，args 改为 ["-y", "tavily-mcp@latest"] 即可。

多个 MCP Server 怎么配？

直接在 stdio.connections 下添加更多连接即可，例如同时接入搜索和文件系统：

spring: ai: mcp: client: type: SYNC initialized: true stdio: connections: tavily: command: cmd.exe args: ["/c", "npx", "-y", "tavily-mcp@latest"] env: TAVILY_API_KEY: ${TAVILY_API_KEY} filesystem: command: cmd.exe args: ["/c", "npx", "-y", "@anthropic/mcp-filesystem@latest", "D:/docs"] 

所有连接的工具会自动合并，模型可以同时使用多个 MCP Server 提供的工具。

五、核心代码：将 MCP 工具挂到 ChatClient

spring-ai-starter-mcp-client 会自动完成以下工作：

1. 启动 MCP Server 子进程
2. 通过 MCP 协议拉取工具列表
3. 将 MCP tools 转换成 Spring AI 的 ToolCallback
4. 注册一个 ToolCallbackProvider Bean 到 Spring 容器

你要做的只有一件事：把 ​ToolCallbackProvider 挂到 ​ChatClient 上。

5.1 AI 自动配置类

@Configuration public class LanjiiAiAutoConfiguration { ​ /** * 聊天记忆（滑动窗口，保留最近 20 条消息） */ @Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.builder() .maxMessages(20) .build(); } ​ /** * 向量存储（用于 RAG，非 MCP 必须） */ @Bean public VectorStore vectorStore(EmbeddingModel embeddingModel) { return SimpleVectorStore.builder(embeddingModel).build(); } } 

5.2 动态构建 ChatClient（核心）

@Component @RequiredArgsConstructor public class DynamicChatClientFactory { ​ private final AiModelConfigService aiModelConfigService; private final AiRolePromptService aiRolePromptService; private final ModelChatStrategyFactory modelChatStrategyFactory; private final ChatMemory chatMemory; private final ToolCallbackProvider toolCallbackProvider; // MCP 自动注入 ​ public ChatClient buildDefaultClient() { AiModelConfig config = aiModelConfigService.getDefaultConfig(); if (config == null) { throw new BizException(ResultCode.NOT_FOUND, "未找到默认启用的模型配置，请先在模型配置中设置默认模型"); } ​ // 通过策略模式动态构建 ChatModel（支持 OpenAI/DeepSeek/智谱 等） ModelChatStrategy strategy = modelChatStrategyFactory .getStrategy(config.getApiProvider()); ChatModel chatModel = strategy.buildChatModel(toModelConfig(config)); ​ String systemPrompt = "你是一个智能助手..."; ​ // 如果配置了角色提示词，优先使用 if (config.getRoleId() != null) { AiRolePrompt rolePrompt = aiRolePromptService.getById(config.getRoleId()); if (rolePrompt != null && rolePrompt.getSystemPrompt() != null) { systemPrompt = rolePrompt.getSystemPrompt(); } } ​ return ChatClient.builder(chatModel) .defaultSystem(systemPrompt) .defaultAdvisors( MessageChatMemoryAdvisor.builder(chatMemory).build() ) .defaultToolCallbacks(toolCallbackProvider) // 关键：挂载 MCP 工具 .build(); } } 

核心就一行：.defaultToolCallbacks(toolCallbackProvider)

这行代码的效果是：

• 模型每次对话时都能"看到"所有 MCP Server 暴露的工具定义
• 模型会根据用户问题自主决定是否调用工具
• 工具调用的请求/响应由 Spring AI + MCP Client 自动处理

5.3 聊天 Service 与 Controller

@Service @RequiredArgsConstructor public class ChatServiceImpl implements ChatService { ​ private final DynamicChatClientFactory dynamicChatClientFactory; ​ @Override public Flux<String> chatStream(String message, String conversationId) { ChatClient chatClient = dynamicChatClientFactory.buildDefaultClient(); ​ return chatClient.prompt() .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId)) .user(message) .stream() .content(); } } 

@RestController @RequestMapping("/chat") @RequiredArgsConstructor public class ChatBotController { ​ private final ChatService chatService; ​ @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(String message, String conversationId) { return chatService.chatStream(message, conversationId); } } 

注意：Controller 和 Service 不需要做任何 MCP 相关的处理。MCP 工具的发现和调用完全由 ChatClient 内部完成，对业务层透明。

六、运行效果

启动应用后，你会在控制台看到 MCP 初始化日志：

i.m.client.transport.StdioClientTransport:106 - MCP server starting. i.m.client.transport.StdioClientTransport:137 - MCP server started 

然后向 /chat/stream?message=今天杭州天气怎么样&conversationId=test1 发请求，模型会：

1. 判断"天气"是实时信息 → 决定调用 tavily_search 工具
2. MCP Client 通过 stdio 将搜索请求发给 tavily-mcp 子进程
3. tavily-mcp 调用 Tavily API 获取搜索结果
4. 搜索结果返回给模型
5. 模型基于搜索结果生成最终回答，流式输出给用户

整个过程模型自主决策，你不需要写任何 if-else 判断"什么时候该搜索"。

七、常见问题与踩坑记录

7.1 Windows 下 stdio 连接必须用 cmd.exe /c

在 Windows 环境下，npx 实际是 .cmd 脚本，不能直接作为 command 启动。必须通过 cmd.exe /c npx ... 来执行，否则会报进程启动失败。

7.2 initialized: true 不可省略

如果不设置 initialized: true，MCP Client 不会在启动时主动初始化，可能导致：

• 第一次对话时工具列表为空，模型不会调用任何工具
• 初始化失败时没有明确的错误日志

7.3 SYNC vs ASYNC 如何选择

• 项目中同时使用了 spring-boot-starter-web（Servlet）→ 选 SYNC
• 纯 WebFlux 响应式应用 → 选 ASYNC
• 混合使用（如本项目引入了 webflux 做流式但主体是 Servlet）→ 选 SYNC

7.4 确保 Node.js/npx 可用

stdio 方式使用 npx 运行 MCP Server，前提是服务器上已安装 Node.js。验证方式：

node -v # 确保有输出，建议 >= 18 npx -v # 确保 npx 可用 

7.5 工具调用超时

默认超时可能不够，尤其是 Tavily 搜索可能耗时较长。建议设置 request-timeout: 60s 或更大值。

八、源码与在线体验

完整源码：https://gitee.com/leven2018/lanjii/tree/master

欢迎 Star ⭐ 和 Fork，项目包含本文涉及的所有代码（MCP 集成、多模型动态切换、RAG 知识库等）。

在线体验：http://106.54.167.194/admin/index

可以直接登录后台，在 AI 对话模块中体验 MCP 工具调用的实际效果。