网站Logo 时光杂货铺

Spring AI MCP 从入门到实战:常见问题与代码示例

admin
40
2026-10-12

基于 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: streamable

4. 启动类

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:8081

3. 调用示例

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 有什么区别?

核心对比

维度

Spring AI 原生 @Tool

MCP 协议

协议标准

Spring 私有规范

行业通用标准,多语言多厂商互通

部署方式

与 AI 应用同进程

独立部署,支持跨语言、跨网络调用

工具复用

仅 Java/Spring 项目可用

任意语言、任意框架均可对接

能力范围

仅工具调用

工具调用、资源访问、Prompt 模板、日志通知

生态兼容

仅 Spring AI 生态

兼容所有支持 MCP 的 AI 客户端和工具服务

选型建议

  • 业务简单、工具都在 Java 项目内:用原生 @Tool 更轻量,无额外部署成本

  • 需要跨语言、跨团队共享工具能力:用 MCP 标准化对接,实现能力复用

  • 需要对接第三方 MCP 生态工具(如各类官方 MCP 服务):必须使用 MCP 客户端

运行注意事项

  1. Spring AI MCP 要求 Spring Boot 3.3+ 版本,JDK 17+

  2. 服务端和客户端的 Spring AI 版本建议保持一致,避免协议不兼容

  3. 生产环境建议使用 Streamable HTTP 协议,性能和兼容性优于 SSE

  4. 敏感业务工具需要添加权限校验,避免大模型越权调用接口

  5. 工具描述(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 的三种方式:

  1. War 包命名控制(最简单):包名即为前缀,如 myapp.war 对应路径 /myapp;ROOT.war 对应根路径。

  2. server.xml 配置:在 <Host> 节点内添加 <Context path="/myapp" docBase="war包路径" />

  3. web.xml 配置:传统 Servlet 项目使用,Spring Boot 不推荐。

1.3 路径拼接错误导致 404 的底层逻辑

请求分为两层匹配,任意一层匹配失败都会返回 404:

完整URL = 域名:端口 / context-path(容器层) / 业务路径(应用层)
  1. 容器层匹配(Tomcat 负责):匹配 context-path,匹配成功则剥掉前缀,把剩余路径交给应用;匹配失败直接返回容器级 404。

  2. 应用层匹配(Spring MVC 负责):匹配业务接口 / 资源路径,匹配失败返回 Spring 级 404。

1.4 高频踩坑点与避坑方案

场景

错误原因

避坑方案

前端漏加前缀

请求缺少 context-path,Tomcat 找不到对应应用

前端统一通过接口前缀变量管理,代码中用 request.getContextPath() 动态获取

Nginx 反向代理路径重复

Nginx 加了前缀,后端也配置 context-path,导致路径叠加两层

Nginx 转发时用 rewrite 去掉前缀,或后端不配置 context-path

重定向 404

sendRedirect("/xxx") 是服务器根路径,会跳过 context-path

重定向拼接前缀:response.sendRedirect(request.getContextPath() + "/xxx")

静态资源 404

HTML 写死绝对路径 /static/xxx.js,不会自动拼接前缀

使用相对路径,或模板引擎路径语法(如 Thymeleaf 的 @{/static/xxx.js})

拦截器匹配失效

拦截器路径多加了 context-path 前缀

拦截器只配置业务路径,不需要加 context-path 前缀

二、MCP 工具调用跳过模型总结(returnDirect)

2.1 为什么要跳过模型总结

MCP 工具调用默认流程:模型决策调用工具 → 执行工具返回结果 → 模型对结果二次总结 → 返回用户 在以下场景中,二次总结不仅无用,反而会带来问题:

  1. 性能损耗:多智能体协作时,每步中间结果都总结会导致延迟倍增、token 成本增加

  2. 数据失真:结构化数据(JSON、业务对象)被模型改写后,无法被下游系统直接解析

  3. 逻辑冗余:本身带推理能力的工具(如 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 验证生效方法

  1. 输出验证:开启 returnDirect 的工具会直接返回原始内容(如 JSON 字符串),没有模型自然语言润色

  2. 日志验证:开启 logging.level.org.springframework.ai.tool=DEBUG,观察工具调用后是否跳过二次推理

  3. 断点验证:在 getToolMetadata 方法中断点,查看 returnDirect 变量是否和服务端配置一致


三、MCP 工具过滤机制

3.1 工具过滤的核心价值

MCP 服务器往往包含大量工具,全部交给模型会带来三个问题:

  1. 浪费 Token:每个工具的描述和 Schema 都会占用上下文,无关工具成为冗余负担

  2. 准确率下降:工具越多,模型选错工具、产生幻觉的概率越高

  3. 权限混乱:多智能体场景下,所有智能体看到全部工具,容易越权调用

工具过滤本质:在客户端对工具进行筛选,只把需要的工具暴露给模型。

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/mcp

4.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_),避免冲突


五、整体最佳实践

  1. 分层控制:Web 层用 context-path 做应用分区,MCP 层用过滤做工具裁剪,权限层用多 ChatClient 做分级

  2. 性能优化:中间节点工具开启 returnDirect 节省延迟,最终输出节点保留模型总结保证体验

  3. 安全兜底:客户端过滤 + 服务端校验双重保障,不依赖客户端过滤做安全控制

  4. 调试排错:开启 DEBUG 日志,通过返回样式快速定位是容器层、应用层还是工具层的问题