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

一、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>

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

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

在 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 不会暴露给模型

多个 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);
    }
}

六、运行效果

启动应用后，你会在控制台看到 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 或更大值。

八、源码与在线体验

完整源码：gitee.com/leven2018/l…

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

在线体验：

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