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

优质文章学习记录

— 8 min read
本文分享在 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（数百个可用），配置即集成。

二、技术栈与版本

组件版本
Spring Boot3.5.9
Spring AI1.1.2
Spring AI MCP Client Starter1.1.2
Java17
MCP Server 示例tavily-mcp (via npx)

三、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 工具调用的实际效果。

Read more

高效AIGC工具推荐：10个热门平台免费与付费功能全指南

高效AIGC工具推荐：10个热门平台免费与付费功能全指南

�� 10大降AIGC平台核心对比速览 排名 工具名称 降AIGC效率 适用场景 免费/付费 1 askpaper ⭐⭐⭐⭐⭐ 学术论文精准降AI 付费 2 秒篇 ⭐⭐⭐⭐⭐ 快速降AIGC+降重 付费 3 Aibiye ⭐⭐⭐⭐ 多学科论文降AI 付费 4 Aicheck ⭐⭐⭐⭐ AI检测+降重一体化 付费 5 白果AI论文 ⭐⭐⭐ 格式规范+降AI 免费/付费 6 文赋AI论文 ⭐⭐⭐ 初稿生成+降AI 免费/付费 7 笔尖AI写作 ⭐⭐⭐ 多场景降AI 免费 8 梅子AI论文 ⭐⭐⭐ 学历适配降AI 付费 9 闪稿AI论文 ⭐⭐ 紧急降AI处理 免费 10

Whisper-large-v3长文本处理：万字级语音转写+智能段落划分演示

Whisper-large-v3长文本处理：万字级语音转写+智能段落划分演示 1. 这不是普通语音转文字——它能读懂万字长录音的“呼吸节奏” 你有没有试过把一场90分钟的技术分享录下来，想转成文字整理笔记，结果发现： * 普通工具卡在3分钟就报错？ * 转出来的文字密不透风，全是连在一起的大段落，根本没法读？ * 中英文混杂的发言，识别错一半，还得逐句核对？ 这次我们实测的 Whisper-large-v3 Web 服务，直接绕开了这些坑。它不只是“把声音变成字”，而是真正理解一段长语音的语义节奏——自动识别说话人停顿、话题切换、语气转折，再把万字转录结果智能切分成逻辑清晰、可读性强的自然段落。 这不是调参炫技，而是面向真实工作流的工程优化：会议纪要、课程听讲、访谈整理、播客文稿……所有需要“听完再消化”的场景，它都能一步到位。 本文全程基于 by113小贝 二次开发的本地化部署版本，不依赖任何云端API，所有音频数据留在你自己的机器里。下面带你从零跑通万字语音转写全流程，重点看它怎么把一整段27分钟的讲座录音，变成结构分明、带时间戳、可直接复制使用的中文文稿。
【2025实测】12款主流降ai率工具大汇总，论文降aigc一篇搞定（含免费降ai率工具）

【2025实测】12款主流降ai率工具大汇总，论文降aigc一篇搞定（含免费降ai率工具）

写论文最怕什么？不是查重，而是那句——“AI率过高”。 现在越来越多学校开始严查论文降aigc报告。我当时AI率高达98%，整个人快崩溃。 为了救回这篇论文，我实测了市面上十几款降ai率工具，从中精选了这12款，有免费的也有付费的，这次全都总结给你，希望能帮你降低ai率。 1、笔灵AI —— 毕业论文首选（专业级降ai） 笔灵AI是我用过最靠谱、降AI率最稳的工具，没有之一。我那篇98%的论文，用它处理后，AI率稳定降到了10%以下。 传送门：https://ibiling.cn/paper-pass?from=ZEEKLOGjiangaigx818https://ibiling.cn/paper-pass?from=ZEEKLOGjiangaigx818 （建议复制到电脑端使用～） * 核心优势：它不是简单的同义词替换，而是采用AIGC重构算法，从句式、语法、逻辑结构上进行深层重构，让文本回归人类书面语风格，真正“去AI痕迹化”。 * 格式保留：这是它的“杀手锏”

Photoshop与AI绘画的无缝对接：Comfy-Photoshop-SD完整使用手册

还在为AI绘画工具与Photoshop之间的频繁切换而烦恼吗？Comfy-Photoshop-SD插件将彻底改变你的创作流程，让Stable Diffusion的强大AI能力直接融入Photoshop的专业环境，实现真正的一站式数字艺术创作体验！🎨 【免费下载链接】Comfy-Photoshop-SDDownload this extension via the ComfyUI manager to establish a connection between ComfyUI and the Auto-Photoshop-SD plugin in Photoshop. https://github.com/AbdullahAlfaraj/Auto-Photoshop-StableDiffusion-Plugin 项目地址: https://gitcode.com/gh_mirrors/co/Comfy-Photoshop-SD 🚀 快速上手：从零开始配置 基础环境准备 首先确保你已安装最新版本的Photoshop，并准备好Auto-Photoshop-SD基础插件。这个插