Spring AI MCP Server正式落地，Java一键部署AI服务保姆级教程

文章目录

- 前言：Java程序员的"USB-C"时刻终于来了
- 一、MCP到底解决了啥痛点？
- 二、环境准备：别在JDK版本上踩坑
- [三、手把手写第一个MCP Server](#三、手把手写第一个MCP Server)
- - [3.1 定义Tool工具类](#3.1 定义Tool工具类)
  - [3.2 注册Tool到MCP Server](#3.2 注册Tool到MCP Server)
  - [3.3 配置文件](#3.3 配置文件)
- [四、两种传输模式：本地stdio vs 远程SSE](#四、两种传输模式：本地stdio vs 远程SSE)
- - [4.1 stdio模式：本地小工具首选](#4.1 stdio模式：本地小工具首选)
  - [4.2 HTTP+SSE模式：企业级部署必看](#4.2 HTTP+SSE模式：企业级部署必看)
- 五、客户端怎么调？ChatClient一键挂接
- 六、实战踩坑记录（血与泪的教训）
- - [6.1 initialized: true不能省](#6.1 initialized: true不能省)
  - [6.2 Windows下的npx坑](#6.2 Windows下的npx坑)
  - [6.3 工具描述要写人话](#6.3 工具描述要写人话)
  - [6.4 超时设置](#6.4 超时设置)
- [七、企业级玩法：Spring AI Alibaba的骚操作](#七、企业级玩法：Spring AI Alibaba的骚操作)
- 结语：Java在AI时代的第二春

无意间发现了一个CSDN大神的人工智能教程，忍不住分享一下给大家。很通俗易懂，重点是还非常风趣幽默，像看小说一样。床送门放这了👉 http://blog.csdn.net/jiangjunshow

前言：Java程序员的"USB-C"时刻终于来了

说实话，过去一年咱们Java程序员在AI圈属实有点憋屈。看着隔壁Python党天天折腾LangChain、LlamaIndex，各种智能体玩得飞起，咱们还在用RestTemplate硬调OpenAI接口，感觉自己像个拿着算盘进网吧的古人。

但2025年5月20号之后，局面变了。Spring AI 1.0 GA正式发布，顺带把MCP（Model Context Protocol，模型上下文协议）这个"大杀器"给整进来了。这玩意儿是啥？你可以把它理解成AI世界的USB-C接口------以前你给大模型接外部工具，得准备一百种转接头，今天换个API格式，明天改个鉴权方式，头都要秃了。现在有了MCP，甭管是查天气、搜数据库还是发邮件，统统一个协议搞定，真正实现"一线走天下"。

更香的是，Spring AI不仅支持当MCP Client（调用别人提供的工具），还能让你用纯Java搭MCP Server（把自己的服务暴露成AI能调用的工具）。这意味着啥？意味着你手里那些尘封已久的Spring Boot老项目，稍微捯饬两下就能变成AI服务，让ChatGPT、Claude、通义千问这些大模型直接调用。不用再写一堆if-else判断模型意图，也不用折腾复杂的Function Calling配置，Spring AI帮你把脏活累活全包了。

今天这篇文章，咱们就手把手教你从零搞一个Spring AI MCP Server，从环境踩坑到代码实战，再到企业级部署方案，保证你看完就能上手搬砖。

一、MCP到底解决了啥痛点？

在MCP出来之前，如果你想让大模型调用外部工具（比如查个数据库或者调个内部API），基本上得手写Function Calling。这个过程有多酸爽？你得定义JSON Schema，得处理模型幻觉（明明没这工具它硬说调了），得自己管鉴权、限流、容错。更坑的是，每个模型厂商的接口还不一样，OpenAI是一套，Claude是一套，国内文心、通义、DeepSeek又各有各的脾气，完全是"一次接入，终身维护"的血亏买卖。

MCP协议是Anthropic在2024年底开源的，2025年开始被各大厂商疯抢支持。它的核心思想很简单：标准化。就像HTTP协议让浏览器能和任何网站通信，MCP让任何AI应用都能以统一的方式发现和使用外部工具。

架构上MCP分三个角色：

Host：就是大模型本身，比如Claude Desktop、ChatGPT，或者你基于Spring AI做的聊天应用
Client：负责跟Server通信的客户端，Spring AI MCP Client干的就是这活
Server：真正干活的服务，提供具体工具能力，比如查天气、操作数据库

Spring AI 1.0 GA把这三层全给封装好了，你只需要写业务逻辑，剩下的协议转换、传输层通信、工具注册，框架自动搞定。

二、环境准备：别在JDK版本上踩坑

搞Spring AI MCP Server之前，得先确保你的开发环境没掉队。以下是2026年最新的版本搭配，别照着老教程用Spring Boot 2.x，否则jar包冲突能让你怀疑人生：

组件	版本要求	说明
Spring Boot	3.5.x+	必须3.x，2.x完全不兼容
Spring AI	1.0.0+	2025年5月GA版本，带MCP支持
Java	17+	别用8了，真的，该升级了
Node.js	18+	如果用stdio方式跑MCP Server，需要npx

Maven依赖配置如下，记得用Spring AI的BOM统一管理版本，别自己硬写版本号，容易踩坑：

xml 复制代码

    1.0.0

这里有个小坑：如果你是在Windows环境下开发，且打算用stdio方式（本地子进程通信），记得确保系统PATH里有Node.js和npx，因为很多MCP Server是用JavaScript写的，需要通过npx启动。

三、手把手写第一个MCP Server

咱们先来个Hello World级别的，让AI能获取当前服务器时间。别小看这个功能，很多大模型其实不知道实时时间，经常会一本正经地胡说"今天是2023年"。

3.1 定义Tool工具类

在Spring AI里，暴露工具只需要一个@Tool注解，比写Controller还简单：

java 复制代码

@Service
public class SystemToolService {

    @Tool(name = "getCurrentTime", description = "获取当前服务器的本地时间")
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }

    @Tool(name = "getSystemStatus", description = "获取系统运行状态，包括CPU和内存使用情况")
    public String getSystemStatus() {
        // 这里可以接入OSHI等库获取真实系统指标，示例简化处理
        return "CPU使用率: 45%, 内存剩余: 2.3GB, 服务运行正常";
    }

}

注意description字段非常重要，这是给大模型看的"说明书"。描述写得越清楚，模型判断该不该调用这个工具就越准确。如果写得太模糊，模型可能会该调用时不调用，或者不该调用时瞎调用，俗称"模型幻觉"。

3.2 注册Tool到MCP Server

写完工具类，得把它注册到MCP Server里。Spring AI提供了ToolCallback机制，一行代码搞定：

java 复制代码

@Configuration
public class McpServerConfig {

    @Bean
    public List toolCallbacks(SystemToolService systemToolService) {
        return List.of(ToolCallbacks.from(systemToolService));
    }

}

3.3 配置文件

application.yml里加上这几行，就完成了一半配置：

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        name: my-java-server    # 你的MCP Server名字
        version: 1.0.0         # 版本号
        type: ASYNC           # SYNC或ASYNC，推荐ASYNC性能更好
        sse-message-endpoint: /mcp/messages  # SSE传输方式的端点

这里type选SYNC还是ASYNC？如果你用的是传统Spring MVC（Servlet栈），选SYNC；如果是WebFlux响应式栈，选ASYNC。不过实测下来，哪怕在Servlet项目里用ASYNC也没啥问题，Spring AI底层帮你屏蔽了差异。

四、两种传输模式：本地stdio vs 远程SSE

MCP协议支持两种传输方式，应用场景完全不同，搞错了会很痛苦。

4.1 stdio模式：本地小工具首选

stdio就是标准输入输出，Spring应用启动一个子进程，通过管道跟MCP Server通信。适合本地开发或者单个工具场景。

配置方式：

yaml 复制代码

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            my-local-server:
              command: java
              args:
                - "-jar"
                - "my-server.jar"
              environment:
                - "API_KEY=sk-xxxx"

Windows用户注意：如果命令是npx或npm这种脚本，得写成cmd.exe /c npx ...，否则进程启动会报错。

4.2 HTTP+SSE模式：企业级部署必看

如果你要把MCP Server部署到服务器上，供多个客户端调用，必须用HTTP+SSE（Server-Sent Events）。这种方式走HTTP协议，可以跨机器通信，还能过网关、做负载均衡。

Spring AI Alibaba 1.0 GA（2025年6月发布）甚至支持把MCP Server注册到Nacos，实现服务发现和负载均衡，这对企业级应用太重要了。想象一下，你公司有10个AI应用都要调用财务系统的MCP Server，直接注册到Nacos，自动搞个集群，不比每个应用硬编码IP地址香？

配置方式：

yaml 复制代码

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            remote-server:
              url: http://localhost:8080
              sse-endpoint: /mcp/messages

五、客户端怎么调？ChatClient一键挂接

服务端写完了，客户端调用简单到离谱。Spring AI MCP Client会自动把Server暴露的工具转换成ToolCallback，你只需要在构建ChatClient时挂上去：

java 复制代码

@Service
public class ChatService {

    private final ChatClient chatClient;

    public ChatService(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) {
        this.chatClient = builder
            .defaultToolCallbacks(toolCallbackProvider)  // 就是这一行，自动获得所有MCP工具
            .build();
    }

    public String chat(String message) {
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }

}

当你问"现在几点了"或者"系统状态怎么样"，大模型会自动识别需要调用工具，然后Spring AI MCP Client会帮你完成：找Server→调工具→拿结果→喂给模型→生成回答。整个过程你是无感知的，就像调了个普通AI接口一样。

六、实战踩坑记录（血与泪的教训）

6.1 initialized: true不能省

很多教程没提这个，但如果不设置initialized: true，MCP Client启动时不会主动去拉工具列表，结果第一次对话时工具列表是空的，模型根本不知道自己能调用啥。加了这配置，启动时会自动初始化，虽然稍微慢几秒，但省心。

6.2 Windows下的npx坑

在Windows上用stdio模式跑JavaScript写的MCP Server（比如Tavily搜索），直接写command: npx会报错。因为npx其实是个cmd脚本，得用cmd.exe /c包裹，或者换成npx.cmd。

6.3 工具描述要写人话

刚开始我写@Tool的description很随意，比如就写个"获取时间"。结果模型老是不调用，或者调用错了。后来改成"获取当前服务器的实时时间，用于回答需要时间基准的问题"，准确率立马上升。这玩意儿本质上是在训练模型的判断逻辑，提示工程那一套在这儿同样适用。

6.4 超时设置

默认的工具调用超时可能只有10秒，如果你的工具要调外部API（比如搜索、查数据库），很容易超时。记得在配置里加大request-timeout：

yaml 复制代码

spring:
  ai:
    mcp:
      client:
        request-timeout: 60s

七、企业级玩法：Spring AI Alibaba的骚操作

如果你是在阿里生态或者需要企业级特性，强烈建议看看Spring AI Alibaba 1.0 GA（2025年6月发布）。它在Spring AI基础上加了几个真香功能：

Nacos MCP Registry：把MCP Server当微服务治理，支持动态上下线、负载均衡。以前改个工具得重启所有客户端，现在直接Nacos控制台操作。
Higress AI网关：通过网关代理模型调用，可以做限流、降级、多模型路由。比如OpenAI挂了自动切到DeepSeek，业务无感知。
JManus平台：可视化编排Agent，支持把多个MCP Server组合成工作流。比如"先查天气→再查库存→最后生成报告"，全程零代码拖拽。

结语：Java在AI时代的第二春

以前总有人说Java不适合搞AI，性能不如Python，生态不如Node.js。但Spring AI MCP Server的落地，让Java后端工程师有了个弯道超车的机会------你手里那些积累了十年的业务系统，那些复杂的权限体系、事务管理、数据库连接池，不用推翻重来，加个@Tool注解就能让AI用上。

2025年被称为AI Agent元年，MCP协议就是这个元年的基础设施。支付宝推出了支付MCP Server，阿里云搞了MCP注册中心，腾讯、百度也在跟进。作为Java开发者，现在上车正是时候。

别等了，把你那个尘封的Spring Boot项目翻出来，加个MCP Server支持，明天就能跟产品经理说："咱系统也支持AI调用，领先行业一大步。"这牛，值得吹。