基于 Spring AI 的 MCP 客户端/服务端架构指南

简介: 本文聚焦于通过Spring AI框架构建本地MCP(模型上下文协议)服务,解决AI大模型在企业应用中的数据孤岛与安全问题。MCP作为开源协议,提供标准化桥梁,使模型能动态调用本地资源,确保数据安全可控。文章详细介绍了环境准备、模块架构、代码实现(包括客户端和服务端)、关键配置及部署方案,并强调了构建要求、协议兼容和异常处理等注意事项。通过实战案例,读者可掌握如何利用MCP突破数据壁垒,构建高效、安全的AI应用。

背景

随着人工智能技术的爆发式增长,企业级应用对AI大模型的分析、推理、生成等能力需求日益迫切。然而,传统模型面临“数据孤岛”困境:大量关键业务数据分散在本地系统、专有数据库或第三方服务中,难以通过简单的提示词直接注入模型,导致模型理解受限、决策质量不足。更严峻的是,对于涉及隐私或合规要求的数据(如企业财务信息、医疗记录等),直接暴露给云端模型存在显著安全风险。如何打破数据壁垒,同时确保敏感信息的安全可控,成为AI落地的核心挑战。


在此背景下,模型上下文协议(MCP)应运而生。这一由Anthropic开源的开放协议,为AI模型与外部数据/工具提供了“标准化桥梁”,通过统一的接口规范,使模型能够动态调用本地文件、数据库、API等资源,实现“上下文感知”的智能交互。MCP的核心价值在于:

  • 标准化集成:告别“一对一”定制开发,通过协议对接即可连接任意兼容MCP的数据源或工具,大幅降低生态构建成本。
  • 安全与灵活性:支持本地部署,数据无需离境,兼顾隐私合规与实时访问需求。
  • 智能体赋能:为AI Agent提供“手脚”,使其能自主执行查询、分析、操作等复杂任务流。


Spring AI作为Java生态中领先的AI开发框架,通过深度集成MCP协议,为开发者提供了企业级解决方案:其模块化架构、对同步/异步通信的支持、以及与Spring Boot的无缝融合,使得构建本地MCP客户端与服务端变得高效且可靠。无论是快速搭建文件系统的本地数据中台,还是构建与业务系统(如CRM、ERP)的实时联动,Spring AI的声明式配置、注解驱动开发模式极大降低了技术门槛。


本文将聚焦于“本地MCP服务建设”实战,详细讲解如何基于Spring AI框架,从零开始搭建MCP客户端与服务端,实现模型与本地资源的的安全交互。通过案例演示,读者将掌握如何通过标准化协议突破数据孤岛,构建既安全可控又具备动态扩展能力的AI应用,为业务智能化升级提供可落地的技术路径。


一、环境准备

1.1 基础环境要求

  • JDK:17+(推荐 JDK 21)
  • Spring Boot:3.4.5(3.x.x 系列)
  • Spring Framework:6.2.6(6.x.x 系列)
  • Spring AI:1.0.0-M7+(M6 之前版本存在已知问题)


二、模块架构

2.1 核心模块

image.png

三、代码实现

3.1 MCP 客户端

Maven 依赖配置

pom.xml

<dependencies>
    <!-- Spring AI Starter -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
    
    <!-- WebFlux 支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>
<!-- 打包配置 -->
<build>
    <finalName>${appname}</finalName>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <goals><goal>repackage</goal></goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Controller示例

McpClientController.java

@RestController
@RequestMapping("/service")
publicclassMcpClientController {
    privatefinal ChatClient chatClient;

    publicMcpClientController(ChatClient.Builder builder, ToolCallbackProvider tools){
        this.chatClient = builder.defaultToolCallbacks(tools).build();
    }

    @GetMapping("/query/currentTime/{country}")
    Flux<String> queryCurrentTime(@PathVariable String country){
        returnthis.chatClient
            .prompt(new PromptTemplate("调用本地工具查询国家{country}当前时间")
                .create(Map.of("country", country)))
            .stream()
            .content();
    }
}

3.2 MCP 服务端

工具类实现

DateTimeTool.java

@Service
publicclassDateTimeTool {
    privatestaticfinal Map<String, String> COUNTRY_MAP = Map.of(
        "c1", "2020-02-01 12:00:00",
        "c2", "2020-02-01 13:00:00"
    );

    @Tool(description = "国家时间查询工具")
    public String getCurrentDateTimeByCountry(String country){
        return COUNTRY_MAP.getOrDefault(country, 
            LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
    }
}

服务配置

McpServerApplication.java

@SpringBootApplication
publicclassMcpServerApplication {
    publicstaticvoidmain(String[] args){
        SpringApplication.run(McpServerApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider tools(DateTimeTool tool){
        return MethodToolCallbackProvider.builder()
            .toolObjects(tool)
            .build();
    }
}

四、关键配置

4.1 客户端配置(application.properties)

application.properties

# 日志调试
logging.level.org.springframework.ai=DEBUG
logging.level.io.modelcontextprotocol=DEBUG

# OpenAI 配置
spring.ai.openai.base-url=${AI_BASE_URL}
spring.ai.openai.api-key=${API_KEY}
spring.ai.openai.chat.options.model=qwen-plus

# MCP 客户端配置
spring.ai.mcp.client.toolcallback.enabled=true
spring.ai.mcp.client.request-timeout=60s
spring.ai.mcp.client.root-change-notification=true
spring.ai.mcp.client.stdio.servers-configuration=classpath:mcp-service.json

4.2 服务端启动配置(mcp-service.json)

mcp-service.json


{
  "mcpServers": {
    "my-mcp-service": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dspring.main.banner-mode=off",
        "-Dlogging.pattern.console=",
        "-jar",
        "/home/admin/app/target/my-mcp-service.jar"
      ]
    }
  }
}

重要提示:必须禁用控制台输出,避免污染 stdio 输入流!

五、部署方案

5.1 打包配置(assembly.xml)

<assembly>
  <id>release</id>
  <formats><format>tar.gz</format></formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <!-- Client 打包 -->
    <fileSet>
      <directory>../mcp-client/target/</directory>
      <includes><include>*.jar</include></includes>
    </fileSet>
    
    <!-- Server 打包 -->
    <fileSet>
      <directory>../mcp-service/target/</directory>
      <includes><include>*.jar</include></includes>
    </fileSet>
  </fileSets>
</assembly>

整合 client/server 生成统一部署jar包,支持通过docker进行标准化部署。


六、注意事项

1.构建要求:

  • Maven 版本需与构建环境匹配;
  • 使用指定 JDK:baseline.jdk=ajdk-21

2.协议兼容:

  • 确保 stdio 通道纯净,避免日志污染;
  • 服务端需禁用 Web 上下文:-Dspring.main.web-application-type=none

3.异常处理:

  • 关注 stdio 通道的异常日志;
  • 建议超时设置 ≥60 秒:spring.ai.mcp.client.request-timeout=60s


来源  |  阿里云开发者公众号

作者  |  轻飏

相关文章
|
27天前
|
存储 人工智能 资源调度
MCP协议深度集成:生产级研究助手架构蓝图
本文详解基于LangGraph与MCP协议构建研究助手的技术方案,涵盖双服务器集成、状态化智能体设计与用户元命令控制,助你掌握生产级代理系统开发要点。
89 1
|
29天前
|
JSON 人工智能 Java
基于Spring AI构建智能Text-to-SQL转换器:一个完整的MCP
Spring AI 更新结构化输出转换器,弃用旧版 Parser 类,引入与 Spring 框架对齐的 Converter 体系,提升命名规范与功能兼容性。新版本支持 JSON、XML 及 Java 对象转换,确保 LLM 输出结构化,便于下游应用处理。
|
22天前
|
人工智能 JavaScript 算法
Playwright携手MCP:AI智能体实现自主化UI回归测试
MCP 协议使得 AI 能够通过 Playwright 操作浏览器,其中快照生成技术将页面状态转化为 LLM 可理解的文本,成为驱动自动化测试的关键。该方式适用于探索性测试和快速验证,但目前仍面临快照信息缺失、元素定位不稳定、成本高、复杂场景适应性差以及结果确定性不足等挑战。人机协同被认为是未来更可行的方向,AI 负责执行固定流程,人类则专注策略与验证。
|
10天前
|
机器学习/深度学习 人工智能 机器人
AI Compass前沿速览:Nano Bananary、MCP Registry、通义DeepResearch 、VoxCPM、InternVLA·M1具身机器人
AI Compass前沿速览:Nano Bananary、MCP Registry、通义DeepResearch 、VoxCPM、InternVLA·M1具身机器人
|
11天前
|
人工智能 Java 机器人
基于Spring AI Alibaba + Spring Boot + Ollama搭建本地AI对话机器人API
Spring AI Alibaba集成Ollama,基于Java构建本地大模型应用,支持流式对话、knife4j接口可视化,实现高隐私、免API密钥的离线AI服务。
243 1
基于Spring AI Alibaba + Spring Boot + Ollama搭建本地AI对话机器人API
|
5天前
|
人工智能 Cloud Native 中间件
划重点|云栖大会「AI 原生应用架构论坛」看点梳理
本场论坛将系统性阐述 AI 原生应用架构的新范式、演进趋势与技术突破,并分享来自真实生产环境下的一线实践经验与思考。
|
25天前
|
人工智能 安全 数据可视化
深度解析三大AI协议:MCP、ACP与A2A,看懂智能代理的通信法则
在AI代理技术快速发展的背景下,MCP、ACP和A2A三大协议成为推动AI生态协作的关键标准。MCP(模型上下文协议)为大模型提供标准化信息接口,提升AI处理外部数据的效率;ACP(代理通信协议)专注于边缘设备间的低延迟通信,实现本地系统的高效协同;A2A(代理对代理协议)则构建跨平台通信标准,打通不同AI系统的协作壁垒。三者各司其职,共同推动AI从独立工具向智能协作团队演进,提升整体智能化水平与应用灵活性。
207 2
深度解析三大AI协议:MCP、ACP与A2A,看懂智能代理的通信法则
|
11天前
|
人工智能 Java 数据库
Spring AI
Spring AI 为 Java 生态注入智能,提供统一抽象接口,简化大模型集成,助力开发者高效构建 AI 应用,推动企业智能化转型。

热门文章

最新文章