一、前言

二、MCP 介绍

2.1 MCP是什么

2.2 MCP 核心特点

2.3 Spring AI MCP 介绍

2.3.1 Spring AI MCP架构

2.3.2 Spring AI MCP分层说明

2.4 两种模式介绍

三、本地开发SSE模式

3.1 搭建mcp-server

3.1.1 导入工程核心依赖

3.1.2 添加配置文件

3.1.3 提供两个Tool

3.1.4 注册Tool

3.2 搭建mcp-client

3.2.1 导入核心依赖

3.2.2 添加配置文件

3.2.3 增加测试接口

3.2.4 效果测试

四、本地开发stdio模式

4.1 server 端开发

4.1.1 导入核心依赖

4.1.2 调整配置文件

4.1.3 提供Tool工具方法

4.1.4 注册工具方法

4.1.5 添加日志文件

4.1.6 构建jar包

4.2 mcp-client 开发

4.2.1 pom文件中导入下面核心依赖

4.2.2 添加下面的配置文件

4.2.3 接口改造

4.2.4 效果测试

五、Spring AI 对接第三方MCP服务

5.1 高德MCP服务前置说明

5.1.2 获取apikey

5.2 代码集成

5.2.1 配置文件信息

5.2.2 增加配置类

5.2.3 增加测试接口

六、写在文末

一、前言

MCP（Model Context Protocol）是一种由 Anthropic 于 2024 年 11 月发布的开源协议，旨在标准化大型语言模型（LLM）与外部数据源和工具的交互。它像“AI的USB-C接口”，通过统一接口让 AI 模型无缝连接数据库、文件、API 等外部资源。随着人工智能技术的发展，越来越多的框架和工具被开发出来，以帮助开发者快速构建智能化的应用程序。Spring AI 是 Spring 家族的一员，它提供了丰富的机器学习和人工智能相关的支持。同时，Spring AI也适应时代的发展，快速跟进，于近期开始了对MCP生态的能力整合，本篇将详细介绍下如何在Spring AI中集成和使用MCP能力。

二、MCP 介绍

2.1 MCP是什么

模型上下文协议（即 Model Context Protocol，MCP）是一个开放协议，它规范了应用程序如何向大型语言模型（LLM）提供上下文。MCP 提供了一种统一的方式将 AI 模型连接到不同的数据源和工具，它定义了统一的集成方式。在开发智能体（Agent）的过程中，我们经常需要将将智能体与数据和工具集成，MCP 以标准的方式规范了智能体与数据及工具的集成方式，可以帮助您在 LLM 之上构建智能体（Agent）和复杂的工作流。目前已经有大量的服务接入并提供了 MCP server 实现，当前这个生态正在以非常快的速度不断的丰富中。

2.2 MCP 核心特点

MCP 具备如下核心特点：

标准化集成
- MCP统一了不同AI模型（如Claude、GPT等）与外部工具（如数据库、API、浏览器等）的交互方式，避免了传统定制化API开发的重复劳动
双向通信
- 不同于传统AI只能被动接收数据，MCP支持AI主动检索信息并执行操作（如更新数据库、触发工作流），实现真正的“代理式AI”
动态上下文管理
- MCP允许AI在会话中持续携带上下文信息（如用户偏好、历史记录），使多步骤任务（如“查询天气→推荐行程→预订酒店”）能自动串联执行
安全与灵活性
- MCP支持本地或云端部署，通过OAuth 2.1认证和数据沙箱机制保障敏感信息的安全访问

2.3 Spring AI MCP 介绍

官网入口：Model Context Protocol (MCP) :: Spring AI Reference

2.3.1 Spring AI MCP架构

Spring 官网对于MCP给出了下面的架构图

从上面的架构图不难看出，Spring AI MCP 采用模块化架构，包括以下组件：

Spring AI 应用程序：使用 Spring AI 框架构建想要通过 MCP 访问数据的生成式 AI 应用程序
Spring MCP 客户端：MCP 协议的 Spring AI 实现，与服务器保持 1:1 连接
MCP 服务器：轻量级程序，每个程序都通过标准化的模型上下文协议公开特定的功能
本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务
远程服务：MCP 服务器可以通过互联网（例如，通过 API）连接到的外部系统

2.3.2 Spring AI MCP分层说明

Spring AI MCP实现遵循三层架构：

三层架构实现说明

Java MCP 实现遵循三层架构：

客户端/服务器层：McpClient 处理客户端操作，McpServer 管理服务器端协议操作
会话层(McpSession)：管理通信模式和状态
传输层(McpTransport)：处理 JSON-RPC 消息的序列化和反序列化，支持多种传输方式

2.4 两种模式介绍

在Spring AI MCP模式下，目前主要提供了2种的通信协议的模式，即SSE和STDIO

STDIO传输协议：

STDIO方式是基于进程间通信，MCP Client和MCP Server运行在同一主机，主要用于本地集成、命令行工具等场景。
优点：
- 简单可靠，无需网络配置；适合本地部署场景；进程隔离，安全性好。
缺点：
- 仅支持单机部署；不支持跨网络访问；每个客户端需要独立启动服务器进程。

SSE传输协议：

SSE（Server-Sent Events）传输层是基于HTTP的单向通信机制，专门用于服务器向客户端推送数据。MCP Client远程调用MCP Server提供的SSE服务。实现客户端和服务端远程通信。
优点：
- 支持分布式部署；可跨网络访问；支持多客户端连接；轻量级，使用标准HTTP协议。
缺点：
- 需要额外的网络配置；相比stdio实现略微复杂；需要考虑网络安全性。

三、本地开发SSE模式

3.1 搭建mcp-server

分别搭建mcp-server 和 mcp-client两个工程，下面依次说明。

3.1.1 导入工程核心依赖

在pom文件中导入下面的核心依赖

<properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><spring-ai.version>1.0.0-M7</spring-ai.version>
</properties><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.4.4</version><relativePath/>
</parent><dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>1.0.0-M7</version><type>pom</type><scope>import</scope></dependency></dependencies>
</dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webflux</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId></dependency>
</dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins>
</build><repositories><repository><id>central</id><url>https://maven.aliyun.com/repository/central</url><releases><enabled>true</enabled></releases><snapshots><enabled>true</enabled></snapshots></repository><repository><name>Central Portal Snapshots</name><id>central-portal-snapshots</id><url>https://central.sonatype.com/repository/maven-snapshots/</url><releases><enabled>false</enabled></releases><snapshots><enabled>true</enabled></snapshots></repository><repository><id>spring-milestones</id><name>Spring Milestones</name><url>https://repo.spring.io/milestone</url><snapshots><enabled>false</enabled></snapshots></repository><repository><id>spring-snapshots</id><name>Spring Snapshots</name><url>https://repo.spring.io/snapshot</url><releases><enabled>false</enabled></releases></repository>
</repositories>

3.1.2 添加配置文件

在配置文件中添加下面的配置信息

spring:ai:mcp:server:name: mcp-serverversion: 1.0.0type: ASYNCsse-message-endpoint: /mcp/messages

3.1.3 提供两个Tool

自定义一个类，增加两个Tool方法，参考下面的代码

package com.congge.tool;import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;import java.time.LocalDateTime;@Service("weatherServiceTool")
public class WeatherServiceTool {@Tool(description = "获取指定城市的天气")public String getWeather(String cityName){if(cityName.equals("北京")){return "晴天";}else if(cityName.equals("上海")){return "阴天";}else {return "未知";}}@Tool(description = "获取当前用户所在的时区时间")String getCurrentDateTime() {return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();}}

3.1.4 注册Tool

提供一个配置类，将上面的Tool方法进行注册

package com.congge.config;import com.congge.tool.WeatherServiceTool;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class ToolCallbackProviderConfig {@Beanpublic ToolCallbackProvider toolCallbackProvider(WeatherServiceTool weatherServiceTool) {return MethodToolCallbackProvider.builder().toolObjects(weatherServiceTool).build();}
}

以上做完之后，启动项目，通过控制台的输出可以看到，注册了2个Tool方法

3.2 搭建mcp-client

mcp-client ，即调用server端提供的大模型工具的客户端，在实际业务中，可以有多个客户端都需要server端提供的各类Tool能力，统称为客户端。

3.2.1 导入核心依赖

在pom文件中导入下面的核心依赖

<properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><spring-ai.version>1.0.0-M7</spring-ai.version></properties><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.4.4</version><relativePath/></parent><dependencies><dependency><groupId>com.alibaba.cloud.ai</groupId><artifactId>spring-ai-alibaba-starter</artifactId><version>1.0.0-M6.1</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client</artifactId></dependency></dependencies><repositories><repository><id>spring-snapshots</id><name>Spring Snapshots</name><url>https://repo.spring.io/snapshot</url><releases><enabled>false</enabled></releases></repository><repository><name>Central Portal Snapshots</name><id>central-portal-snapshots</id><url>https://central.sonatype.com/repository/maven-snapshots/</url><releases><enabled>false</enabled></releases><snapshots><enabled>true</enabled></snapshots></repository><repository><id>spring-milestones</id><name>Spring Milestones</name><url>https://repo.spring.io/milestone</url><snapshots><enabled>false</enabled></snapshots></repository><repository><id>spring-snapshots</id><name>Spring Snapshots</name><url>https://repo.spring.io/snapshot</url><releases><enabled>false</enabled></releases></repository></repositories><dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>1.0.0-M7</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>

3.2.2 添加配置文件

在配置文件中添加如下信息

spring:ai:dashscope:api-key: 你的apikeymcp:client:sse:connections:server1:url: http://localhost:8080toolcallback:enabled: true

3.2.3 增加测试接口

增加一个测试接口，用于测试调用server端的Tool能力

package com.congge.web;import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/client/ai")
public class ChatController {private final ChatClient chatClient;public ChatController(ChatClient.Builder chatClientBuilder) {this.chatClient = chatClientBuilder.build();}@Resourceprivate ToolCallbackProvider toolCallbackProvider;//localhost:8082/client/ai/chat?message=今天北京的天气如何//localhost:8082/client/ai/chat?message=你是谁//localhost:8082/client/ai/chat?message=当前时间是多少@GetMapping("/chat")public String chat(String message){return chatClient.prompt().user(message).tools(toolCallbackProvider.getToolCallbacks()).call().content();}
}

3.2.4 效果测试

下面通过几个不同的测试场景分别验证下server端提供的工具能力是否生效

1）测试效果一

调用接口：localhost:8082/client/ai/chat?message=今天北京的天气如何， 问题是Tool工具中相关的，可以给出预期的结果

2）测试效果二

调用接口：localhost:8082/client/ai/chat?message=你是谁， 问题是Tool工具中非相关的

3）测试效果三

调用接口：localhost:8082/client/ai/chat?message=当前时间是多少， 问题是Tool工具中相关的，可以给出预期的结果

四、本地开发stdio模式

基于stdio的MCP服务端通过标准输入输出流与客户端通信，适用于作为子进程被客户端启动和管理的场景，非常适合嵌入式应用。

通过Java开发工具创建一个springboot工程，模拟开发一个算术计算器服务，通过stdio传输协议发布为MCP Server。

4.1 server 端开发

4.1.1 导入核心依赖

在pom中导入如下核心的依赖

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

4.1.2 调整配置文件

在配置文件中添加下面的配置信息

server:port: 8088spring:ai:mcp:server:name: mcp-stdio-serverversion: 1.0.0

4.1.3 提供Tool工具方法

可以复用上一个案例中的工具方法

4.1.4 注册工具方法

同上一个案例

4.1.5 添加日志文件

为了方便后续查看运行过程中的日志，在resources目录下增加一个日志配置文件logback-spring.xml

<configuration><appender name="FILE" class="ch.qos.logback.core.FileAppender"><file>mcp-server.log</file><encoder><pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern></encoder></appender><root level="INFO"><appender-ref ref="FILE" /></root>
</configuration>

4.1.6 构建jar包

到这里，一个通过Spring AI创建的MCP Server完成了。stdio方式是server和client通过进程通信，所以需要把server打包成jar，以便client命令启动执行。

jar包的完整路径：E:\code-self\517\server\mcp-server\target\mcp-server-1.0-SNAPSHOT.jar

测试该服务是否发布成功，在cmd命令行窗口里输入如下命令：

java -Dspring.ai.mcp.server.stdio=true -Dspring.main.web-application-type=none -Dspring.main.banner-mode=off -jar E:/code-self/517/server/mcp-server/target/mcp-server-1.0-SNAPSHOT.jar

至此，我们通过spring ai框架开发完成了2个MCP Server服务，一个通过sse协议发布，另一个通过stdio协议发布，接下来，开发一个MCP Client端，调用这两个MCP Server服务。

4.2 mcp-client 开发

4.2.1 pom文件中导入下面核心依赖

导入下面核心依赖，之前的可以保持不变

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId><version>1.0.0-M6</version>
</dependency>

4.2.2 添加下面的配置文件

配置文件中添加下面的配置信息

args参数中根据你的包的实际路径填写

server:port: 8082spring:ai:dashscope:api-key: 你的apikeychat:options:#model: qwen-maxmodel: qwen-plusmcp:client:connection-timeout: 60stype: ASYNCstdio:connections:server2:command: javaargs:- -Dspring.ai.mcp.server.stdio=true- -Dspring.main.web-application-type=none- -Dspring.main.banner-mode=off- -jar- D:/self-code/0522/mcp-server/target/mcp-server.jar

另一种方式是在resource目录下增加一个配置文件，比如叫做：mcp-servers-config.json ，然后将上述的args里面的参数放到该json文件中，如下：

{"mcpServers": {"weather": {"command": "java","args": ["-Dspring.ai.mcp.server.stdio=true","-Dspring.main.web-application-type=none","-Dspring.main.banner-mode=off","-jar","E:/code-self/517/集成/mcp-server/target/mcp-server.jar"],"env": {}}}
}

最后，再重新调整下原始的配置文件，改为对该json文件的引用即可

server:port: 8082spring:ai:mcp:client:stdio:servers-configuration: classpath:/mcp-servers-config.json
#          connections:
#            server2:
#              command: java
#              args:
#                - -Dspring.ai.mcp.server.stdio=true
#                - -Dspring.main.web-application-type=none
#                - -Dspring.main.banner-mode=off
#                - -jar
#                - D:/self-code/0522/mcp-server/target/mcp-server.jardashscope:api-key: 你的apikeychat:options:#模型名称： qwen-plus  deepseek-v3  deepseek-r1model: qwen-plus

以上这两种方式任选其一即可，更推荐引用json文件的方式，这样方便全局管理

4.2.3 接口改造

在原来的测试接口中做一些调整，参考下面的代码，主要是把ToolCallbackProvider 配置到ChatClient 中

package com.congge.web;import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/client/ai")
public class ChatController {private final ChatClient chatClient;public ChatController(ChatClient.Builder chatClientBuilder,ToolCallbackProvider tools) {this.chatClient = chatClientBuilder.defaultTools(tools).build();}@Resourceprivate ToolCallbackProvider toolCallbackProvider;//localhost:8082/client/ai/chat?message=今天北京的天气如何//localhost:8082/client/ai/chat?message=你是谁//localhost:8082/client/ai/chat?message=当前时间是多少@GetMapping("/chat")public String chat(String message){return chatClient.prompt().user(message).tools(toolCallbackProvider.getToolCallbacks()).call().content();}
}

4.2.4 效果测试

仿照上面的案例测试，问一个与Tool中无关的问题，和一个相关的问题

1）测试效果一

调用接口：localhost:8082/client/ai/chat?message=你是谁， 问题是Tool工具中非相关的

2）测试效果二

调用接口：http://localhost:8082/client/ai/chat?message=当前时间是多少

五、Spring AI 对接第三方MCP服务

随着MCP的概念火了之后，也有很多平台开始逐步开放自己的MCP，利用这些平台的能力即可快速对接各类特定场景下的MCP服务，从而为自身的应用赋能，下面介绍一下如何在自己的Spring AI应用中对接第三方的MCP服务。下面的案例中以高德地图提供的MCP服务为例进行说明。

5.1 高德MCP服务前置说明

使用高德MCP服务有多个渠道，第一种是直接通过高德开放平台本身进行对接，第二种是通过第三方平台对接高德MCP服务，比如阿里云百炼平台。

入口地址一：概述-MCP Server | 高德地图API

入口地址二：百炼控制台

5.1.2 获取apikey

在后文的代码中，为了集成并使用高德的mcp服务时，需要用到apikey，因此需要提前在高德开放平台注册账号并获取apikey，参考该文档即可完成apikey 的获取：创建应用和 Key-MCP Server | 高德地图API

最后在控制台，我的应用这里就能看到你创建的这个应用的apikey信息了

5.2 代码集成

在代码中集成高德MCP也很简单，官方提供的参考文档地址：快速接入-MCP Server | 高德地图API，下面看代码中的集成过程。

5.2.1 配置文件信息

在工程配置文件中，增加下面的配置信息

spring:ai:dashscope:api-key: 你的apikeychat:options:model: qwen-maxmcp:client:connection-timeout: 60stype: ASYNC

5.2.2 增加配置类

在工程中增加如下配置类

package com.congge.tool;import com.fasterxml.jackson.databind.ObjectMapper;
import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
import io.modelcontextprotocol.spec.McpClientTransport;
import org.springframework.ai.mcp.client.autoconfigure.NamedClientMcpTransport;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import java.util.Collections;
import java.util.List;@Configuration
public class McpConfig {@Beanpublic List<NamedClientMcpTransport> mcpClientTransport() {McpClientTransport transport = HttpClientSseClientTransport.builder("https://mcp.amap.com").sseEndpoint("/sse?key=你的高德的apikey").objectMapper(new ObjectMapper()).build();return Collections.singletonList(new NamedClientMcpTransport("amap", transport));}}

5.2.3 增加测试接口

添加如下测试接口，用于测试效果

package com.congge.web;import io.modelcontextprotocol.client.McpAsyncClient;
import io.modelcontextprotocol.spec.McpSchema;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;import java.util.List;
import java.util.Map;@RestController
@RequestMapping("/client/mcp")
public class McpController {@AutowiredList<McpAsyncClient> mcpAsyncClients;//localhost:8082/client/mcp/test@RequestMapping("/test")public Mono<McpSchema.CallToolResult> test() {var mcpClient = mcpAsyncClients.get(0);return mcpClient.listTools().flatMap(tools -> {//logger.info("tools: {}", tools);System.out.println(tools);return mcpClient.callTool(new McpSchema.CallToolRequest("maps_weather",Map.of("city", "北京")));});}}

启动工程后，调用一下上述的接口，成功返回了数据，实际应用时，可以进一步参考官方API对相应的字段进行解析使用