Spring AI：MCP实现方案

原创于 2025-07-16 20:15:00 发布 · 1k 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#spring #人工智能 #java

springAi 专栏收录该内容

6 篇文章

订阅专栏

是以圣人处无为之事，行不言之教

通过前面章节的详细介绍，我们已经对MCP协议有了深入理解，并且掌握了调用MCP Server的具体方法。本章将详细讲解如何基于Spring AI框架搭建属于自己的MCP Server，包括从依赖配置到代码实现的完整流程。

在这里插入图片描述

Spring AI为MCP Server的开发提供了完善的支持，大幅简化了开发流程。借助其封装的组件和自动配置能力，我们无需关注底层通信细节，只需通过简单的配置和代码编写，就能快速搭建一个功能完备的MCP Server。

前面我们已经学习了如何创建本地工具方法（Tools），而MCP Server的搭建正是基于这些本地方法，通过添加特定依赖和配置来实现服务化暴露。下面将分步骤详细说明具体实现过程：

一、模式说明

目前MCP协议支持两种通信模式：

STDIO（标准输入输出）：基于标准输入输出流进行通信，适用于简单的命令行交互场景
SSE（服务器发送事件）：基于HTTP的服务器推送技术，适用于需要持续数据交互的场景
在Spring AI框架中，这两种模式的核心开发方式完全一致，主要区别在于服务启动和暴露的方式不同，我们可以根据实际场景选择合适的模式。

二、添加依赖

代码仓库：spring-ai-demo（分支：test3）

首先需要在项目的pom.xml文件中添加MCP Server的相关依赖。Spring AI提供了WebFlux和传统MVC两种版本的starter，可根据项目所使用的Web框架进行选择：

WebFlux模式（适用于响应式编程场景）：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

MVC模式（适用于传统Spring MVC场景）：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

添加依赖后，Maven会自动引入相关的核心组件，包括MCP协议处理、服务暴露、工具方法注册等功能所需的类库。

三、配置MCP Server

接下来需要在配置文件（如application.properties或application.yml）中添加MCP Server的相关配置，以定义服务的基本信息和暴露方式。以下是完整的配置示例：

# 服务名称（自定义，用于标识当前MCP Server）
spring.ai.mcp.server.name="demo-ai-webFlux-mcp-server-stdio"
# 服务类型（ASYNC表示异步模式，适用于SSE等场景；SYNC表示同步模式，适用于STDIO）
spring.ai.mcp.server.type=ASYNC
# 服务版本号
spring.ai.mcp.server.version=1.0.0
# 服务描述信息（用于说明当前MCP Server的功能）
spring.ai.mcp.server.instructions="本地执行服务：提供基于时间的行动代号生成功能"
# SSE消息端点（仅WebFlux/MVC模式需要，定义客户端连接的地址）
spring.ai.mcp.server.sse-message-endpoint=/mcp/messages
# 服务支持的能力配置（true表示支持该能力）
spring.ai.mcp.server.capabilities.tool=true # 支持工具调用
spring.ai.mcp.server.capabilities.resource=true # 支持资源访问
spring.ai.mcp.server.capabilities.prompt=true # 支持提示词处理
spring.ai.mcp.server.capabilities.completion=true # 支持内容生成

上述配置中，sse-message-endpoint仅在使用WebFlux或MVC模式时需要配置，STDIO模式无需此配置。capabilities相关配置用于声明当前MCP Server支持的功能，客户端可根据这些信息决定如何与服务端交互。

四、编写本地工具方法（Tools）

MCP Server的核心功能是提供可被调用的本地方法，这些方法需要使用@Tool注解进行标识，以便Spring AI自动识别并注册为MCP服务接口。以下是一个示例工具类：

import org.springframework.ai.core.Tool;
import org.springframework.ai.core.ToolParam;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClientException;

@Service
public class McpServerService {

    /**
     * 通过日期获取行动代号
     * @param data 输入的日期（格式示例：2024-07-16）
     * @return 生成的行动代号字符串
     * @throws RestClientException 如果处理过程中发生异常
     */
    @Tool(description = "根据输入的日期生成对应的行动代号，输入参数为日期字符串")
    public String getActionMark(@ToolParam(description = "需要生成行动代号的日期，格式为yyyy-MM-dd") String data) {
        // 实际业务逻辑：这里简单拼接字符串作为示例，实际场景可根据需求实现复杂逻辑
        return "代号：牛逼" + data;
    }
}

在上述代码中：

@Service注解将该类注册为Spring Bean，使其能够被自动扫描和管理
@Tool注解用于标识该方法是一个可被MCP客户端调用的工具方法，description属性用于描述该方法的功能，将被用于生成服务元数据
@ToolParam注解用于描述方法参数的含义，帮助客户端理解如何传递参数

五、注册工具方法

编写好工具类后，需要将其注册到MCP Server中，以便服务端能够识别并对外提供这些方法。这可以通过在Spring Boot启动类中定义ToolCallbackProvider类型的Bean来实现：

import org.springframework.ai.mcp.server.tool.MethodToolCallbackProvider;
import org.springframework.ai.mcp.server.tool.ToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class DemoAiWebFluxApplication {

    public static void main(String[] args) {
        // 启动Spring Boot应用
        SpringApplication.run(DemoAiWebFluxApplication.class, args);
    }

    /**
     * 注册工具方法到MCP Server
     * @param mcpServerService 包含工具方法的服务类实例
     * @return 工具回调提供者，用于MCP Server处理客户端调用
     */
    @Bean
    public ToolCallbackProvider registerTools(McpServerService mcpServerService) {
        // 将工具类实例传入，构建工具回调提供者
        return MethodToolCallbackProvider.builder()
                .toolObjects(mcpServerService) // 可以传入多个工具类实例，用逗号分隔
                .build();
    }
}

通过上述配置，Spring AI 会自动扫描mcpServerService中被@Tool注解标识的方法，并将其注册为 MCP Server 的可调用接口。

六、客户端调用配置

MCP Server 启动后，客户端可以通过配置连接信息来调用其提供的服务。以下是 SSE 模式下的客户端配置示例（在客户端项目的 application.properties 中配置）：

 # 配置MCP客户端连接信息
 spring.ai.mcp.client.sse.connections.myServer.url= http://localhost:8080
 # 可选：配置连接超时时间
 # spring.ai.mcp.client.sse.connections.myServer.timeout=30000

其中，myServer是自定义的连接名称，url为MCP Server的地址（即我们搭建的服务地址）。如果使用STDIO模式，客户端配置方式略有不同，具体可参考前面章节的详细说明。

七、执行结果说明

当客户端成功连接到MCP Server并调用getActionMark方法时，服务端会执行对应的逻辑并返回结果。例如，客户端传入参数2024-07-16，服务端将返回：

代号：牛逼2024-07-16

至此，我们已完成基于Spring AI的MCP Server搭建全过程。通过这种方式，我们可以快速将本地方法服务化，供其他系统通过MCP协议调用，实现功能的复用和集成。

八、工具注册机制详解

在Spring AI的MCP Server框架中，ToolCallbackProvider是工具方法注册的核心接口，它有多个实现类，分别适用于不同的调用场景和处理方式。以下是AsyncMcpToolCallbackProvider、MethodToolCallbackProvider、StaticToolCallbackProvider和SyncMcpToolCallbackProvider的区别与作用：

核心区别总结

实现类	核心特点	适用场景	依赖注解/Bean
`MethodToolCallbackProvider`	自动扫描`@Tool`注解的Bean方法	绝大多数基于Spring Bean的常规场景	依赖
`StaticToolCallbackProvider`	手动注册静态工具，无注解依赖	动态工具定义、非Spring管理的方法	不依赖
`SyncMcpToolCallbackProvider`	同步阻塞执行，适配同步通信	短耗时同步方法、STDIO模式	可选
`AsyncMcpToolCallbackProvider`	异步非阻塞执行，适配异步通信	长耗时异步方法、SSE流式响应	可选

实际应用建议

日常开发优先使用MethodToolCallbackProvider，通过@Tool注解快速注册工具方法
如需动态定义工具（非Spring Bean），选择StaticToolCallbackProvider
同步/异步适配类（SyncMcpToolCallbackProvider/AsyncMcpToolCallbackProvider）通常作为底层适配，无需手动创建，框架会根据服务类型（spring.ai.mcp.server.type）自动选择
通过选择合适的ToolCallbackProvider实现类，我们可以灵活应对不同的业务场景，既可以快速开发常规服务，也能满足特殊场景下的定制化需求。

九、MCP Server和tools的区别

MCP Server 和 tools 在功能上有明显区别。MCP Server 是连接大模型与外部世界的桥梁，具备工具调用、资源访问和提供对话模板等功能。而 tools 是 MCP Server 提供的可执行函数，主要功能是让大模型能与外部系统交互并执行特定操作。

对比项目	MCP Server	tools
功能性质	是连接大模型与外部资源的服务端程序，提供多种核心能力，是一个综合性的服务平台。	是 MCP Server 提供的可执行函数，是大模型实现特定操作的具体 “技能”。
主要功能	1. 工具服务：允许大模型根据任务需求自主调用预设的工具函数或外部服务。 2. 资源服务：提供对本地或远程资源的只读访问，支持读取文件、数据库等数据。 3. 模板服务：提供预设对话模板和提示词，引导交互流程。	主要是让大模型能与外部系统交互并执行特定操作，如天气查询、邮件发送、API 调用等。
数据处理能力	可整合多种数据资源，为大模型提供统一的数据访问层，能处理结构化数据（如数据库数据）与非结构化数据（如文档、日志），例如 StarRocks MCP Server 让 AI 无缝对接 StarRocks 数据库与其他数据。	通常针对特定任务处理数据，如某个工具可能专门用于从特定 API 获取数据并进行简单处理，数据处理范围相对较窄。
应用场景	适用于需要长期提供服务、支撑核心业务流程的场景，如企业级应用中持续为业务系统提供 AI 能力支持，或在物联网场景中实时处理设备数据等。	适用于大模型在对话或任务执行过程中，需要借助外部功能来完成特定步骤的场景，如用户询问天气时，大模型调用天气查询工具获取结果。
操作自主性	MCP Server 本身是被动响应大模型的调用请求，根据预设配置和协议提供服务。	由大模型根据任务需求自主决定是否调用，模型判断需要执行特定操作时才会触发工具调用。
安全控制	通常具备企业级安全机制，如权限控制、数据加密等，确保服务稳定和数据安全，如部分 MCP Server 支持内网穿透与权限控制。	除了依赖 MCP Server 的安全机制外，自身也可能有用户批准等安全控制措施，防止未经授权的操作。