基于 Spring AI 官方 MCP 实现,整理从概念、服务端搭建、自定义工具开发到客户端调用的全流程示例,所有代码均附带详细注释,可直接运行验证。
问题 1:什么是 MCP?Spring AI 提供了哪些 MCP 能力?
核心概念
MCP(Model Context Protocol,模型上下文协议)是一套标准化的 AI 工具调用协议,定义了大模型与外部工具 / 数据源交互的统一规范,解决了不同厂商工具调用格式不兼容的问题。
Spring AI 基于官方 MCP Java SDK 提供了完整的 Spring Boot 集成能力:
服务端:快速将现有 Spring Bean 暴露为 MCP 工具,支持 STDIO、SSE、Streamable HTTP 多种传输协议
客户端:一键对接任意 MCP 服务,自动将 MCP 工具转换为 Spring AI 可调用的 Function
注解驱动:通过
@McpTool、@McpToolParam注解快速开发工具,无需手写 JSON Schema
问题 2:如何搭建一个最简 MCP 服务端?
实现说明
基于 Spring Boot WebMvc 搭建 HTTP 协议的 MCP 服务端,仅需 3 步:引入依赖、编写工具类、添加配置。
完整 Demo 代码
1. pom.xml 核心依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<!-- Spring Boot 父项目,要求 3.3+ 版本 -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.4.0</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>mcp-weather-server</artifactId>
<version>0.0.1-SNAPSHOT</version>
<dependencies>
<!-- Spring AI MCP 服务端 WebMvc 启动器 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
</dependencies>
<!-- Spring AI 版本统一管理 -->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.0.0-M5</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
</project>2. 工具服务类(核心)
package com.example.mcpweather.service;
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Service;
/**
* 天气查询 MCP 工具服务
* 加 @Service 交给 Spring 容器管理,Spring AI 自动扫描 @McpTool 注解的方法并注册为 MCP 工具
*/
@Service
public class WeatherService {
/**
* 根据城市名称查询当前温度
* @McpTool 标记该方法为 MCP 可调用工具,description 用于大模型理解工具用途
* @McpToolParam 标记参数说明,required 标识是否必填
*/
@McpTool(description = "获取指定城市的当前气温,单位为摄氏度,包含天气状况和风力信息")
public String getTemperature(
@McpToolParam(description = "城市名称,例如:北京、上海、巴黎", required = true) String city) {
// 这里模拟天气查询,实际项目可对接第三方天气API(如Open-Meteo、高德天气)
return String.format("【%s】当前气温:22°C,晴转多云,风力2级", city);
}
}3. application.yml 配置
server:
port: 8080 # 服务端口,客户端通过该端口连接
spring:
application:
name: mcp-weather-server
ai:
mcp:
server:
# MCP服务名称,客户端通过名称识别服务
name: weather-server
# 服务版本号
version: 1.0.0
# 传输协议:streamable(推荐,性能更好)/ sse
protocol: streamable4. 启动类
package com.example.mcpweather;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* MCP 服务端启动类
* 启动后自动扫描所有 @McpTool 注解的方法并对外提供服务
*/
@SpringBootApplication
public class McpWeatherServerApplication {
public static void main(String[] args) {
SpringApplication.run(McpWeatherServerApplication.class, args);
}
}启动后访问 http://localhost:8080 即可提供 MCP 服务,客户端可通过该地址连接并调用天气工具。
问题 3:如何开发复杂的自定义 MCP 工具?
实现说明
支持多参数、复杂返回类型、参数校验,可直接对接业务系统(如数据库、第三方接口),Spring AI 自动生成工具的 JSON Schema 描述。
Demo 代码:订单查询 MCP 工具
package com.example.mcpdemo.tool;
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;
/**
* 订单查询 MCP 工具类
* 模拟对接业务订单系统,向大模型暴露订单查询能力
* 加 @Component 交给 Spring 容器管理即可被自动扫描
*/
@Component
public class OrderMcpTools {
/**
* 根据订单号查询订单详情
* 支持多参数,返回结构化数据,Spring AI 自动生成 JSON Schema
*/
@McpTool(
name = "queryOrderDetail",
description = "根据订单号查询订单状态和详情,仅支持查询最近90天内的订单。" +
"返回字段包括:订单状态、实付金额、下单时间、收货地址、物流单号"
)
public Map<String, Object> queryOrder(
@McpToolParam(description = "订单号,格式为ord-xxxxxxxxxx,10位数字后缀", required = true) String orderNo,
@McpToolParam(description = "下单用户ID,用于权限校验", required = true) Long userId) {
// 模拟数据库查询,实际项目可注入Mapper/Service调用真实业务接口
Map<String, Object> orderDetail = new HashMap<>();
orderDetail.put("orderNo", orderNo);
orderDetail.put("userId", userId);
orderDetail.put("status", "已发货");
orderDetail.put("amount", 299.00);
orderDetail.put("createTime", LocalDateTime.now().minusDays(2).toString());
orderDetail.put("address", "湖北省武汉市洪山区XX街道XX小区");
orderDetail.put("logisticsNo", "SF1234567890");
orderDetail.put("logisticsCompany", "顺丰速运");
return orderDetail;
}
/**
* 查询用户待收货订单数量
* 单参数工具方法示例
*/
@McpTool(description = "查询当前用户的待收货订单总数量")
public Integer countPendingReceiptOrders(
@McpToolParam(description = "用户ID", required = true) Long userId) {
// 模拟业务查询
return 3;
}
}问题 4:如何搭建 MCP 客户端并调用远程 MCP 工具?
实现说明
MCP 客户端负责连接远程 MCP 服务,将服务端的工具自动转换为 Spring AI 的 Function Callback,注入到 ChatClient 中即可被大模型自动识别和调用。
Demo 代码
1. pom.xml 依赖
<dependencies>
<!-- Spring AI MCP 客户端启动器 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
<!-- 大模型实现,这里以通义千问为例,也可替换为OpenAI、Anthropic等 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-dashscope</artifactId>
</dependency>
</dependencies>2. application.yml 配置
spring:
ai:
# 大模型配置
dashscope:
api-key: ${DASHSCOPE_API_KEY:你的API密钥}
chat:
options:
model: qwen-max
# MCP 客户端配置
mcp:
client:
streamable-http:
connections:
# 连接上面搭建的天气MCP服务,key为服务标识
weather-server:
url: http://localhost:8080
# 可继续添加订单服务等其他MCP服务
order-server:
url: http://localhost:80813. 调用示例
package com.example.mcpclient;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.mcp.client.ToolCallbackProvider;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class McpClientApplication {
public static void main(String[] args) {
SpringApplication.run(McpClientApplication.class, args);
}
/**
* 启动后自动执行测试
* ToolCallbackProvider 是 MCP 客户端核心,封装了所有已连接MCP服务的工具
*/
@Bean
public CommandLineRunner mcpToolTest(ChatClient.Builder chatClientBuilder,
ToolCallbackProvider mcpToolCallbackProvider) {
return args -> {
// 构建 ChatClient 并注入 MCP 工具
ChatClient chatClient = chatClientBuilder
// 注入所有 MCP 工具,大模型可根据问题自动识别调用
.defaultToolCallbacks(mcpToolCallbackProvider.getToolCallbacks())
// 添加对话记忆,支持多轮工具调用
.defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
.build();
// 测试1:询问天气,大模型会自动调用天气MCP工具获取数据
String weatherResponse = chatClient
.prompt("帮我查一下北京今天的天气怎么样")
.call()
.content();
System.out.println("天气查询结果:\n" + weatherResponse);
System.out.println("------------------------");
// 测试2:查询订单,大模型会自动调用订单MCP工具
String orderResponse = chatClient
.prompt("用户ID是1001,帮我查一下订单ord-2026010101的详情")
.call()
.content();
System.out.println("订单查询结果:\n" + orderResponse);
};
}
}问题 5:如何同时对接多个不同协议的 MCP 服务?
实现说明
MCP 客户端支持同时配置 HTTP、STDIO 等多种协议的 MCP 服务连接,所有服务的工具会统一聚合,大模型可根据需求自动选择调用。
完整配置示例
spring:
ai:
mcp:
client:
# 1. HTTP协议的MCP服务(Spring Boot实现的服务端)
streamable-http:
connections:
# 天气服务
weather-server:
url: http://localhost:8080
# 订单服务
order-server:
url: http://localhost:8081
# 2. STDIO协议的MCP服务(例如Node.js实现的第三方MCP工具)
stdio:
connections:
# Brave搜索引擎MCP服务(官方社区提供)
brave-search:
command: npx
args: ["-y", "@modelcontextprotocol/server-brave-search"]
env:
BRAVE_API_KEY: ${BRAVE_API_KEY:你的搜索API密钥}
# 文件系统MCP服务(本地文件读写能力)
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]配置完成后,ToolCallbackProvider 会自动聚合所有服务的工具,无需额外代码,大模型即可同时使用天气查询、订单查询、网页搜索、文件读写等多种能力。
问题 6:MCP 与 Spring AI 原生 Function Calling 有什么区别?
核心对比
选型建议
业务简单、工具都在 Java 项目内:用原生
@Tool更轻量,无额外部署成本需要跨语言、跨团队共享工具能力:用 MCP 标准化对接,实现能力复用
需要对接第三方 MCP 生态工具(如各类官方 MCP 服务):必须使用 MCP 客户端
运行注意事项
Spring AI MCP 要求 Spring Boot 3.3+ 版本,JDK 17+
服务端和客户端的 Spring AI 版本建议保持一致,避免协议不兼容
生产环境建议使用 Streamable HTTP 协议,性能和兼容性优于 SSE
敏感业务工具需要添加权限校验,避免大模型越权调用接口
工具描述(description)尽量清晰准确,直接影响大模型调用的准确率
Spring AI MCP 实战进阶与避坑完全指南
本文档整合了 Spring Boot Web 上下文路径配置、Spring AI MCP 工具调用优化、工具过滤、多权限分级等核心实战内容,包含底层原理说明、常见踩坑点、可直接运行的带注释代码。
一、Spring Boot context-path 配置与 404 踩坑详解
1.1 核心作用
context-path 是 Web 应用的统一访问前缀,用于在同一服务器 / 端口下区分不同的 Web 应用。配置后所有接口、静态资源的访问路径都需要加上此前缀。
示例:配置
server.servlet.context-path=/myapp,访问地址变为http://域名:端口/myapp/接口路径
1.2 两种部署场景的配置方式
1.2.1 内置 Tomcat(Jar 包启动,Spring Boot 默认)
这是最常用的场景,有 3 种配置方式,优先级:命令行参数 > 代码配置 > 配置文件。
配置文件方式(推荐)
根据 Spring Boot 版本选择对应配置项,是最常见的踩坑点:
server:
servlet:
# Spring Boot 2.x / 3.x 标准配置项
# 注意:必须以 / 开头,不能以 / 结尾
context-path: /myapp踩坑提醒:Spring Boot 1.x 配置项为 server.context-path(无 servlet 中间层),在高版本中配置会完全不生效。
命令行启动参数(临时修改用)
# 方式1:Spring Boot 启动参数
java -jar demo.jar --server.servlet.context-path=/myapp
# 方式2:JVM 系统参数
java -Dserver.servlet.context-path=/myapp -jar demo.jar代码自定义配置(动态场景用)
@Configuration
public class WebConfig {
/**
* 自定义 Web 服务器配置,动态设置 context-path
*/
@Bean
public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> webServerCustomizer() {
// factory 为内置 Tomcat 配置工厂,直接设置上下文路径
return factory -> factory.setContextPath("/myapp");
}
}1.2.2 外置 Tomcat(War 包部署)
核心坑点:Spring Boot 的 server.servlet.context-path 对外置 Tomcat 完全失效,因为此时使用的是外部 Tomcat 容器。
外置 Tomcat 配置 context-path 的三种方式:
War 包命名控制(最简单):包名即为前缀,如
myapp.war对应路径/myapp;ROOT.war对应根路径。server.xml 配置:在
<Host>节点内添加<Context path="/myapp" docBase="war包路径" />web.xml 配置:传统 Servlet 项目使用,Spring Boot 不推荐。
1.3 路径拼接错误导致 404 的底层逻辑
请求分为两层匹配,任意一层匹配失败都会返回 404:
完整URL = 域名:端口 / context-path(容器层) / 业务路径(应用层)容器层匹配(Tomcat 负责):匹配 context-path,匹配成功则剥掉前缀,把剩余路径交给应用;匹配失败直接返回容器级 404。
应用层匹配(Spring MVC 负责):匹配业务接口 / 资源路径,匹配失败返回 Spring 级 404。
1.4 高频踩坑点与避坑方案
二、MCP 工具调用跳过模型总结(returnDirect)
2.1 为什么要跳过模型总结
MCP 工具调用默认流程:模型决策调用工具 → 执行工具返回结果 → 模型对结果二次总结 → 返回用户 在以下场景中,二次总结不仅无用,反而会带来问题:
性能损耗:多智能体协作时,每步中间结果都总结会导致延迟倍增、token 成本增加
数据失真:结构化数据(JSON、业务对象)被模型改写后,无法被下游系统直接解析
逻辑冗余:本身带推理能力的工具(如 RAG、知识图谱),二次总结会破坏原有严谨性
returnDirect=true 的效果:工具执行完成后,跳过模型二次推理,直接把工具原始结果返回给用户。
2.2 原生 returnDirect 的生效局限
本地 Function Call:
@Tool(returnDirect = true)注解直接生效远程 MCP 工具:Spring AI 原生
SyncMcpToolCallback没有从 MCP 协议元数据中读取returnDirect字段,默认永远为 false,配置注解不生效
2.3 自定义实现:MCP 远程工具支持单粒度 returnDirect
通过继承原生类,重写元数据获取逻辑,从 MCP 工具的 annotations 字段动态读取 returnDirect 标记,实现单个工具粒度控制。
2.3.1 自定义工具回调类(核心扩展)
package com.example.mcp.config;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema;
import org.springframework.ai.mcp.SyncMcpToolCallback;
import org.springframework.ai.tool.metadata.ToolMetadata;
/**
* 支持单工具粒度控制 returnDirect 的 MCP 工具回调
* 继承原生 SyncMcpToolCallback,保留所有原生能力
* 仅从 MCP 工具的 annotations 元数据中读取 returnDirect 配置,覆盖对应字段
*/
public class ReturnDirectSyncMcpToolCallback extends SyncMcpToolCallback {
// 当前工具的完整元数据,用于读取自定义注解
private final McpSchema.Tool tool;
/**
* 构造方法,传入 MCP 客户端和对应工具
* @param client MCP 同步客户端
* @param tool 当前工具的元数据对象
*/
public ReturnDirectSyncMcpToolCallback(McpSyncClient client, McpSchema.Tool tool) {
super(client, tool);
this.tool = tool;
}
/**
* 重写元数据获取方法,动态注入 returnDirect 配置
* @return 工具元数据
*/
@Override
public ToolMetadata getToolMetadata() {
// 1. 先获取原生的完整元数据(保留 description、inputSchema 等所有信息)
ToolMetadata originalMetadata = super.getToolMetadata();
// 2. 从 MCP 工具的 annotations 中读取 returnDirect 标记,默认 false
boolean returnDirect = false;
if (tool.annotations() != null) {
String returnDirectValue = tool.annotations().get("returnDirect");
returnDirect = "true".equalsIgnoreCase(returnDirectValue);
}
// 3. 基于原生元数据构建新对象,只覆盖 returnDirect 字段
return ToolMetadata.builder()
.from(originalMetadata)
.returnDirect(returnDirect)
.build();
}
}2.3.2 自定义工具回调提供器
package com.example.mcp.config;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.util.ToolUtils;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 自定义 MCP 工具回调提供器
* 替换原生 SyncMcpToolCallbackProvider,生成支持单工具 returnDirect 的回调实例
*/
@Slf4j
public class PerToolReturnDirectMcpToolCallbackProvider extends SyncMcpToolCallbackProvider {
// 所有 MCP 客户端列表
private final List<McpSyncClient> mcpClients;
public PerToolReturnDirectMcpToolCallbackProvider(List<McpSyncClient> mcpClients) {
super(mcpClients);
this.mcpClients = mcpClients;
}
/**
* 遍历所有 MCP 客户端的工具,生成自定义回调实例
* @return 所有可用工具的回调数组
*/
@Override
public ToolCallback[] getToolCallbacks() {
List<ToolCallback> toolCallbacks = new ArrayList<>();
// 遍历所有 MCP 客户端
for (McpSyncClient mcpClient : mcpClients) {
List<McpSchema.Tool> toolList = Collections.emptyList();
try {
// 获取当前客户端的所有工具列表
toolList = mcpClient.listTools().tools();
} catch (Exception e) {
// 单个客户端获取失败不影响其他客户端,跳过并打印警告
log.warn("获取 MCP 客户端工具列表失败,跳过该客户端", e);
continue;
}
// 为每个工具生成自定义回调实例
for (McpSchema.Tool tool : toolList) {
toolCallbacks.add(new ReturnDirectSyncMcpToolCallback(mcpClient, tool));
}
}
ToolCallback[] callbackArray = toolCallbacks.toArray(new ToolCallback[0]);
// 复用原生工具名校验逻辑,避免重复工具名导致调用异常
List<String> duplicateToolNames = ToolUtils.getDuplicateToolNames(callbackArray);
if (!duplicateToolNames.isEmpty()) {
throw new IllegalStateException(
"存在重复名称的 MCP 工具: " + String.join(", ", duplicateToolNames));
}
return callbackArray;
}
}2.3.3 Spring 配置注入
@Configuration
public class McpReturnDirectConfig {
/**
* 注册自定义 MCP 工具回调提供器,替代原生实现
* @param mcpSyncClients 项目中所有 MCP 同步客户端
* @return 自定义工具提供器实例
*/
@Bean
public PerToolReturnDirectMcpToolCallbackProvider perToolReturnDirectMcpToolCallbackProvider(
List<McpSyncClient> mcpSyncClients) {
return new PerToolReturnDirectMcpToolCallbackProvider(mcpSyncClients);
}
}2.3.4 MCP 服务端标记方式
在 MCP 服务端给需要跳过总结的工具添加 returnDirect=true 注解,客户端会自动识别:
// MCP 服务端:开启 returnDirect 的工具
@Bean
public ToolRegistration getWeatherTool() {
return ToolRegistration.builder()
.name("getWeather")
.description("根据城市查询天气")
.inputType(WeatherRequest.class)
.tool(request -> new WeatherResult(request.city(), "晴", 25))
// 关键:添加自定义注解,标记该工具直接返回结果
.annotation("returnDirect", "true")
.build();
}
// 不需要跳过总结的工具,不加注解即可
@Bean
public ToolRegistration queryUserTool() {
return ToolRegistration.builder()
.name("queryUser")
.description("查询用户信息")
.inputType(UserRequest.class)
.tool(request -> userService.queryUser(request.userId()))
.build();
}2.4 验证生效方法
输出验证:开启 returnDirect 的工具会直接返回原始内容(如 JSON 字符串),没有模型自然语言润色
日志验证:开启
logging.level.org.springframework.ai.tool=DEBUG,观察工具调用后是否跳过二次推理断点验证:在
getToolMetadata方法中断点,查看 returnDirect 变量是否和服务端配置一致
三、MCP 工具过滤机制
3.1 工具过滤的核心价值
MCP 服务器往往包含大量工具,全部交给模型会带来三个问题:
浪费 Token:每个工具的描述和 Schema 都会占用上下文,无关工具成为冗余负担
准确率下降:工具越多,模型选错工具、产生幻觉的概率越高
权限混乱:多智能体场景下,所有智能体看到全部工具,容易越权调用
工具过滤本质:在客户端对工具进行筛选,只把需要的工具暴露给模型。
3.2 原生 McpToolFilter 使用方法
Spring AI 提供了 McpToolFilter(本质是 BiPredicate<McpConnectionInfo, McpTool>),对每个工具进行判断,返回 true 保留、false 过滤。
// 构建工具提供器时配置过滤规则
SyncMcpToolCallbackProvider provider = SyncMcpToolCallbackProvider.builder()
.mcpClients(List.of(mcpClient))
// 过滤规则:只保留工具名以 weather 开头的工具
.toolFilter((connectionInfo, tool) -> tool.name().startsWith("weather"))
.build();3.3 原生过滤的局限性
静态过滤:应用启动时一次性过滤完成,之后不再变化,无法针对单个用户动态调整
全局生效:整个应用共用一套过滤规则,无法实现多角色差异化
适用场景:全局固定工具范围、启动时规则就确定的场景
3.4 常用过滤规则示例
// 1. 按工具名前缀过滤
.toolFilter((conn, tool) -> tool.name().startsWith("order_"))
// 2. 按工具描述关键字过滤
.toolFilter((conn, tool) -> tool.description().contains("财务"))
// 3. 按 MCP 服务器过滤(多服务器场景)
.toolFilter((conn, tool) -> conn.serverName().equals("business-server"))
// 4. 组合规则:排除管理员工具 + 只保留业务工具
.toolFilter((conn, tool) ->
!tool.name().startsWith("admin_") && tool.name().startsWith("biz_")
)四、多权限分级的 MCP 工具分配方案
4.1 方案选型
针对「会员用户使用付费 MCP 服务器、普通用户仅用免费 MCP 服务器」的需求,采用多 ChatClient 实例方案:
不同权限对应独立的 ChatClient 实例,启动时初始化对应工具
业务层根据用户身份选择对应 ChatClient,性能稳定、实现简单
适合角色数量少(2-3 种)、权限固定的场景
4.2 完整实现代码
4.2.1 Maven 核心依赖
<dependencies>
<!-- Spring Boot Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring AI OpenAI 兼容驱动 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-openai</artifactId>
<version>1.0.0</version>
</dependency>
<!-- Spring AI MCP 支持 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp</artifactId>
<version>1.0.0</version>
</dependency>
<!-- MCP HTTP 流式客户端 -->
<dependency>
<groupId>io.modelcontextprotocol</groupId>
<artifactId>mcp-client-http</artifactId>
<version>0.6.0</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
</dependencies>4.2.2 配置文件(application.yml)
spring:
ai:
openai:
api-key: 你的模型API密钥
base-url: 你的模型接口地址
chat:
options:
model: gpt-4o-mini
# MCP 服务器配置
mcp:
free:
# 免费 MCP 服务器地址
url: http://127.0.0.1:8001
endpoint: api/mcp
paid:
# 付费 MCP 服务器地址
url: http://127.0.0.1:8002
endpoint: api/mcp4.2.3 MCP 客户端与 ChatClient 配置
package com.example.mcp.config;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.http.HttpClientStreamableHttpTransport;
import io.modelcontextprotocol.spec.McpSchema;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.time.Duration;
import java.util.List;
/**
* 多权限 ChatClient 配置
* 构建普通用户、会员用户两套独立的 ChatClient,分别注入对应权限的 MCP 工具
*/
@Configuration
public class McpPermissionConfig {
@Value("${mcp.free.url}")
private String freeMcpUrl;
@Value("${mcp.free.endpoint}")
private String freeMcpEndpoint;
@Value("${mcp.paid.url}")
private String paidMcpUrl;
@Value("${mcp.paid.endpoint}")
private String paidMcpEndpoint;
/**
* 免费 MCP 服务器客户端
* 所有用户都可以访问该服务器的工具
*/
@Bean
public McpSyncClient freeMcpClient() {
// 构建 HTTP 流式传输
HttpClientStreamableHttpTransport transport = HttpClientStreamableHttpTransport
.builder(freeMcpUrl)
.endpoint(freeMcpEndpoint)
.build();
// 创建同步 MCP 客户端
McpSyncClient client = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("free-client", "1.0"))
.requestTimeout(Duration.ofSeconds(15))
.build();
// 初始化连接
client.initialize();
return client;
}
/**
* 付费 MCP 服务器客户端
* 仅会员用户可以访问该服务器的工具
*/
@Bean
public McpSyncClient paidMcpClient() {
HttpClientStreamableHttpTransport transport = HttpClientStreamableHttpTransport
.builder(paidMcpUrl)
.endpoint(paidMcpEndpoint)
.build();
McpSyncClient client = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("paid-client", "1.0"))
.requestTimeout(Duration.ofSeconds(15))
.build();
client.initialize();
return client;
}
/**
* 普通用户 ChatClient
* 仅注入免费 MCP 服务器的工具,同时过滤掉管理员工具
*/
@Bean("commonChatClient")
public ChatClient commonChatClient(ChatModel chatModel, McpSyncClient freeMcpClient) {
SyncMcpToolCallbackProvider freeProvider = SyncMcpToolCallbackProvider.builder()
.mcpClients(List.of(freeMcpClient))
// 额外过滤:免费服也排除管理员工具
.toolFilter((conn, tool) -> !tool.name().startsWith("admin_"))
.build();
return ChatClient.builder(chatModel)
.defaultToolCallbacks(freeProvider.getToolCallbacks())
.build();
}
/**
* 会员用户 ChatClient
* 同时注入免费 + 付费两套 MCP 服务器的全部工具
*/
@Bean("vipChatClient")
public ChatClient vipChatClient(ChatModel chatModel,
McpSyncClient freeMcpClient,
McpSyncClient paidMcpClient) {
SyncMcpToolCallbackProvider allProvider = SyncMcpToolCallbackProvider.builder()
.mcpClients(List.of(freeMcpClient, paidMcpClient))
.build();
return ChatClient.builder(chatModel)
.defaultToolCallbacks(allProvider.getToolCallbacks())
.build();
}
}4.2.4 业务服务层
package com.example.mcp.service;
import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
/**
* 对话业务服务
* 根据用户身份选择对应权限的 ChatClient 执行对话
*/
@Service
public class ChatService {
// 普通用户客户端
@Resource(name = "commonChatClient")
private ChatClient commonChatClient;
// 会员用户客户端
@Resource(name = "vipChatClient")
private ChatClient vipChatClient;
/**
* 对话入口
* @param userId 用户ID
* @param question 用户问题
* @return 模型回答结果
*/
public String chat(String userId, String question) {
// 判断用户是否为会员(实际项目替换为真实会员校验逻辑)
boolean isVip = checkUserIsVip(userId);
// 根据权限选择对应的 ChatClient
ChatClient client = isVip ? vipChatClient : commonChatClient;
// 执行对话,自动调用对应权限的 MCP 工具
return client.prompt(question)
.call()
.content();
}
/**
* 模拟会员校验逻辑
* 实际项目替换为数据库查询、缓存校验等真实逻辑
* @param userId 用户ID
* @return true-会员,false-普通用户
*/
private boolean checkUserIsVip(String userId) {
return userId != null && userId.startsWith("vip_");
}
}4.2.5 测试接口
package com.example.mcp.controller;
import com.example.mcp.service.ChatService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import jakarta.annotation.Resource;
@RestController
public class ChatController {
@Resource
private ChatService chatService;
/**
* 对话测试接口
* @param userId 用户ID,vip_开头为会员
* @param question 用户问题
* @return 回答结果
*/
@GetMapping("/chat")
public String chat(@RequestParam String userId,
@RequestParam String question) {
return chatService.chat(userId, question);
}
}4.3 进阶:结合 returnDirect 能力
如果需要给付费工具开启直接返回,只需将配置类中的原生 SyncMcpToolCallbackProvider 替换为第二章的自定义 PerToolReturnDirectMcpToolCallbackProvider 即可:
@Bean("vipChatClient")
public ChatClient vipChatClient(ChatModel chatModel,
McpSyncClient freeMcpClient,
McpSyncClient paidMcpClient) {
// 使用支持单工具 returnDirect 的自定义提供器
PerToolReturnDirectMcpToolCallbackProvider provider =
new PerToolReturnDirectMcpToolCallbackProvider(List.of(freeMcpClient, paidMcpClient));
return ChatClient.builder(chatModel)
.defaultToolCallbacks(provider.getToolCallbacks())
.build();
}4.4 安全注意事项
重要提醒:工具过滤只是「让模型看不到工具」,属于前端隐藏,不能替代后端权限校验。
必须在 MCP 服务端对付费工具增加用户身份校验,防止恶意绕过模型直接调用工具接口
多 MCP 服务器存在同名工具时,建议在服务端给工具名加前缀(如
free_、paid_),避免冲突
五、整体最佳实践
分层控制:Web 层用 context-path 做应用分区,MCP 层用过滤做工具裁剪,权限层用多 ChatClient 做分级
性能优化:中间节点工具开启 returnDirect 节省延迟,最终输出节点保留模型总结保证体验
安全兜底:客户端过滤 + 服务端校验双重保障,不依赖客户端过滤做安全控制
调试排错:开启 DEBUG 日志,通过返回样式快速定位是容器层、应用层还是工具层的问题