Spring AI 2.x 集成 MCP 实战：stdio 与 SSE 文件工具调用全攻略

MCP 这个缩写今年在 AI 工程圈里出现频率有多高，不用我多说。Spring AI 2.x 已经把它当成一等公民来支持，但很多人按文档写完配置，MCP Server 也在日志里显示起来了，真让模型去调一次工具，却死活看不见实际效果——要么模型回答“我无法直接访问文件系统”，要么工具方法压根没出现在日志里。这篇文章就是一次手把手的 MCP 实践：以 filesystem MCP Server 为例子，把 stdio 和 SSE 两种传输方式都跑通，并且真正调用到文件工具。适合两类人：一是想搞懂 Spring AI 2.x MCP 链路的新手，二是已经连上 MCP 但工具调不通、想排查的人。

1. 为什么先拿 filesystem 当第一个 MCP Server

1.1 MCP 与 Spring AI 2.x 的组织方式

MCP 全称 Model Context Protocol，模型上下文协议。它要解决的核心问题很简单：大模型的能力边界是它只能“说话”，不能直接动操作系统里的东西。为了让它能读文件、查数据库、调第三方服务，需要一个标准化的工具调用协议。MCP 就是给“模型 - 工具”之间定了一个统一的“插座标准”。

Spring AI 2.x 里，MCP 不再是一个边缘集成，而是融进了自动配置体系。你引入 spring-ai-starter-mcp-client 之后，Spring Boot 启动时就会根据配置去连接 MCP Server，拉取服务器上暴露的工具清单，再把它们注册到 ChatClient 的能力集合里。后面模型在回答问题时，如果判定需要读文件，会自己发起一次 MCP 工具调用，结果再回填到对话上下文。

一个容易误解的点是：MCP 里的“Server”并不一定是一个 HTTP 服务。它只是一种角色的称呼，表示“工具的提供方”。提供方可以是一个本地子进程，通过 stdin/stdout 通信，也可以是一个 HTTP 端点，通过 SSE 事件流通信。搞懂这一点，后续选型就不会被绕晕。

1.2 filesystem 官方工具包到底带了什么

filesystem 是 MCP 官方参考实现之一，npm 包名是 @modelcontextprotocol/server-filesystem。为什么拿它做第一个实验对象？因为它是纯本地文件操作，不需要申请外部账号、不需要鉴权流程、不依赖网络稳定性，出错时排查链路短，问题只会出现在协议配置或目录权限上。

它暴露的工具大致如下，这张表可以直接抄走：

每个工具都有清晰的输入参数元数据和描述信息。Spring AI 客户端在启动时能拿到这些描述，模型也会参考描述来决定何时调用。这也是为什么 filesystem 特别适合做入门实验：你能直观看到“工具描述如何影响模型决策”。

1.3 SSE、stdio 是谁？怎么选？

stdio 全称 Standard Input/Output，方式是 Spring Boot 应用作为父进程，直接拉起一个子进程执行 MCP Server 命令，父子进程之间通过标准输入输出传输 JSON-RPC 消息。优点：部署简单、延迟低、生命周期跟随主应用，本地开发体验好。

SSE 全称 Server-Sent Events，是一种基于 HTTP 的服务端推送单向事件流技术。MCP 用它做传输时，MCP Server 是一个可访问的 HTTP 端点，客户端通过建立 SSE 连接后接收工具调用请求/响应事件。优点：可以跨网络、可以容器化部署、可以供多个客户端复用同一个工具服务。

选型建议：如果 MCP Server 和 Spring Boot 应用在同一台机器、同一个内网环境，优先 stdio；如果你要对接一个中心化部署的 MCP 服务，或者需要网关统一鉴权，优先 SSE。实践中很多人拿 SSE 去连本地 npx 启动的 stdio 服务，那是没理解两种传输方式的差别，自然跑不通。

2. 跑通前的环境与配置清单

2.1 Maven 依赖与版本对齐

Spring AI 2.x 要求 Spring Boot 3.4.x 及以上，具体版本以你引入时的官方兼容矩阵为准。建议直接用 spring-boot-starter-parent 管理版本，避免手动核对 Spring AI 和 Spring Boot 的版本对应关系。

pom.xml 里至少要有这几样：

<dependencies> <!-- Spring AI MCP 客户端，内含 stdio / SSE 两种传输的实现 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-client</artifactId> </dependency> <!-- 模型接入，以 OpenAI 兼容接口为例，也可以用智谱、Ollama 等 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies>

如果在 SSE 环节想自己用 Spring Boot 暴露一个 MCP Server 端点，还需要补这个依赖：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-mcp-server-webmvc</artifactId> </dependency>

版本不用自己写，交给 Spring Boot 父 POM 管理即可。国内访问 Maven Central 时注意仓库镜像配置，否则依赖下载可能卡半天，甚至反复超时。我第一次搭建时就是因为镜像没配好，光下依赖就浪费了将近一个小时。

2.2 安装 filesystem Server 并确定授权目录

filesystem MCP Server 基于 Node.js，先确认环境里有 node：

node -v npm -v

安装有两种方式。全局安装后直接执行：

npm install -g @modelcontextprotocol/server-filesystem mcp-server-filesystem /tmp/mcp-workspace

或者用 npx 一次性拉起：

npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-workspace

注意最后的目录参数是必须的，表示这个 MCP Server 只允许访问这个目录及其子目录。你可以传多个目录。强烈建议单独建一个实验目录，不要直接授权根目录或用户主目录，否则一旦模型误操作，后果不可控。filesystem 的目录授权是它最有价值的防线，别浪费这个功能。

Windows 用户注意：路径写法用绝对路径，比如 D:\mcp-workspace，如果路径有空格，Spring AI 配置里要用数组形式传参，避免被 shell 拆词。我后面会在 stdio 实操部分专门讲这个坑。

2.3 模型接入与最小配置

MCP 工具调用只有配合支持 Function Calling 的模型才有效。当前主流云模型基本都支持。如果你想本地做验证，Ollama 拉一个 qwen2.5 或 llama3.1 也能跑，但模型对工具的选择能力和执行可靠性会弱一些，踩坑概率更大。我个人建议先用 OpenAI 兼容接口或智谱这类云端模型跑通链路，再用本地模型做对照实验。

application.yml 里最小配置类似：

spring: application: name: spring-ai-mcp-demo ai: model: chat: options: api-key: ${AI_API_KEY} model-name: ${AI_MODEL:gpt-4o-mini}

如果用 OpenAI 兼容网关，可能需要额外指定 base-url 参数。各家模型配置略有差异，以 Spring AI 对应文档为准。关键是先确保一个最普通的对话能通，再叠加 MCP 配置，否则后面排查的时候变量太多，没法定位问题。这个顺序很关键，我见过不少人在模型接口都没调通的情况下就急着折腾 MCP，结果越陷越深。

3. 先走 stdio：最直接的“真调工具”路线

3.1 stdio 模式下 Spring AI 配置

在 application.yml 里加一段：

spring: ai: mcp: client: enabled: true name: filesystem-stdio-client type: STDIO command: npx args: - -y - "@modelcontextprotocol/server-filesystem" - "D:/mcp-workspace"

启动应用时会看到类似这样的日志，具体措辞以你用的版本为准：

MCP Client started with transport: STDIO Connected to MCP Server: filesystem-stdio-client Registered tool: list_directory Registered tool: read_file Registered tool: write_file ... Registered tool: search_files

看到 Registered tool 列表才说明 MCP Server 真的挂上了。如果启动日志里没有任何工具注册记录，先别急着写业务代码，停下来排查进程是否拉起成功。这一步没做对，后面所有“真调工具”都是空中楼阁。

3.2 启动检查：看进程、看工具注册

stdio 模式下，Spring AI 会以子进程方式拉起命令。如果命令路径写错，或者 npx 在 Windows 上需要写成 npx.cmd，这里就会失败。检查手段也很简单：单独在终端里跑一遍 Spring AI 将要执行的命令，比如：

npx -y @modelcontextprotocol/server-filesystem D:/mcp-workspace

命令能正常阻塞运行，说明命令本身没问题。接着看 Spring Boot 日志里是否出现“Connected to MCP Server”字样。Spring AI 2.x 比较贴心，工具发现完成后会逐个打印注册的工具名。要注意：如果你看到配置 Type=STDIO，但进程列表里没有 node 子进程，八成是 command 或 args 配错了。

还有一个容易被忽略的细节：子进程的工作目录。如果 MCP Server 依赖相对路径去加载配置或文件，工作目录不对时可能表现异常。实在排查不出问题时，可以在配置里显式指定工作目录，比如 process 相关参数或直接切换启动位置验证。多数情况下，这一步不需要动，但知道有这个参数能少走弯路。

3.3 真调一个文件工具

配好之后，写一个最简单的接口来验证。定义一个 ChatClient Bean：

@Configuration public class AiConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder.build(); } }

再写一个测试接口：

@RestController public class McpDemoController { private final ChatClient chatClient; public McpDemoController(ChatClient chatClient) { this.chatClient = chatClient; } @GetMapping("/mcp/demo") public String demo(@RequestParam(defaultValue = "帮我查看 D:/mcp-workspace 目录下有哪些文件，并逐个列出文件名。") String prompt) { return chatClient.prompt() .user(prompt) .call() .content(); } }

启动 Spring Boot，访问：

curl "http://localhost:8080/mcp/demo"

如果链路是通的，你会看到模型真的返回了目录下的文件列表，而不是“很抱歉，我无法访问您的本地文件”这类话。这才是“真调工具”完成的标志：模型根据你的提问，自主选择了 MCP 暴露的某个文件工具，拿到真实结果，再组织成自然语言回答。整个过程中你可以留意一下耗时——本地 stdio 模式通常比 SSE 模式的工具调用延迟低不少，这就是子进程管道的优势。

3.4 stdio 的几个关键细节（Windows 坑、日志归属）

第一个坑：Windows 下用 npx，命令要写成 npx.cmd，否则 fork 进程时可能找不到可执行文件。这是个非常典型的报错，卡住过不少人。Spring AI 在 Windows 上运行时对命令字符串的解析方式与 Linux 有差异，配置里直接写 npx 不一定好用，改成 npx.cmd 通常立刻解决。

第二个坑：stdio 模式下，子进程的 stdout 是 MCP 协议通道，绝对不能往 stdout 里塞业务日志，否则会污染协议包，出现解析错乱。filesystem 官方实现已经处理好了这一点，不需要你操心。但如果你以后自定义 MCP Server，这是必踩项目。日志请走 stderr，Spring AI 会把它纳入应用日志体系。

第三个坑：子进程生命周期。stdio 模式下，Spring Boot 应用退出时一般会主动关掉子进程，但遇到 kill -9 这类强杀进程时，子进程可能变成孤儿进程残留在系统里。开发机上长时间反复重启，会攒下一堆 node 僵尸进程。我建议跑完实验后随手清理：

ps -ef | grep mcp

或者 Windows 上：

tasklist | grep node

看到残留的 node 进程，确认是你之前实验留下的，再手动结束掉，别影响后面调试。

4. 再走 SSE：跨越网络连接 MCP Server

4.1 SSE 链路的两种搭建方式

官方 filesystem 包默认只暴露 stdio，没有自带 HTTP 服务。要把它包装成 SSE 端点，常见有两种方式。

一种是借助社区桥接工具，把 stdio 的 MCP Server 转成一个 SSE 端点供客户端访问。这类桥接工具本身是一个中间层，实际生产环境中不太建议长期依赖，因为多一层转发就多一个故障点，可观测性也会变差。

另一种更稳妥、更贴合 Spring AI 生态的做法：直接用 Spring AI 的 MCP Server 模块，让 Spring Boot 应用自己也成为一个 MCP Server，暴露文件系统操作相关的工具方法，客户端通过 SSE 来访问。下面我演示的是第二种，因为它在 Spring AI 体系内闭环，不需要额外的 Node 进程做桥接，依赖更少，也更好理解。

4.2 用 Spring Boot 暴露 MCP SSE 端点（含文件工具）

先加依赖 spring-ai-mcp-server-webmvc（前面提过）。然后在配置类里定义 MCP Server 和文件工具：

@Configuration(proxyBeanMethods = false) public class McpServerConfig { @Tool(description = "列出指定目录下的所有文件名和子目录名") public String listDirectory(@ToolParam(description = "绝对路径") String path) { File dir = new File(path); String[] names = dir.list(); if (names == null) { return "目录不存在或无法访问"; } return String.join(", ", names); } @Tool(description = "读取指定文件的文本内容") public String readFile(@ToolParam(description = "文件绝对路径") String path) { try { return Files.readString(Path.of(path)); } catch (IOException e) { return "读取失败: " + e.getMessage(); } } }

Spring AI 2.x 会通过工具自动发现机制，把这些 @Tool 方法收集起来，暴露成 MCP Server 的工具。配合 webmvc 模块，应用起来后会自动提供一个 MCP SSE 端点，默认路径是 /sse，具体以版本日志为准。

启动日志里你应该能看到：

MCP Server started at http://localhost:8080/sse Registered tool: listDirectory Registered tool: readFile

这一步相当于把一个 Spring Boot 应用变成了 MCP Server。它和官方 filesystem 包的差别在于：协议是 MCP 标准，工具是文件操作，效果等价，但完全跑在 JVM 体系内，日志、监控、部署全都能复用已有的 Java 生态。

4.3 客户端用 SSE 连接并真调工具

现在再起一个 Spring Boot 应用作为 MCP 客户端，或者同一个应用里同时开客户端也不冲突。客户端配置：

spring: ai: mcp: client: enabled: true name: filesystem-sse-client type: SSE urls: http://localhost:8080/sse

注意这里 type 是 SSE，连接地址是服务端的 SSE 端点。启动后同样观察工具注册日志。然后复用前面那个 ChatClient 接口，把提示词换成“用 listDirectory 工具查看 D:/mcp-workspace 目录下的文件名”，模型就会走一遍 SSE 链路，把工具执行结果返回。

和 stdio 的区别主要在通信层：stdio 是本地子进程管道，SSE 是 HTTP 长连接。对上层业务代码来说，ChatClient 的调用方式完全一样。这就是 Spring AI 抽象的价值：传输方式可以换，业务代码不需要重写。我自己在项目里从本地 stdio 切到远程 SSE，业务层一个字符都没改，只动了配置。

4.4 SSE 流式输出与 abort 的一点经验

SSE 本身也是大模型流式回答常用的承载方式。日常项目中，模型回答实时渲染通常就是把 call() 换成 stream()：

chatClient.prompt() .user(prompt) .stream() .content();

配合前端 EventSource 或 fetch 流式读取，就能实现打字机效果。而 abort 场景一般是用户停止生成时，前端断开连接或发一个取消请求，Spring AI 侧使用可取消的响应流或调整超时来配合。注意，MCP 工具调用在流式链路里同样工作，只是你看到的效果是：文字一段一段出来，中间如果模型决定调工具，会出现一个等待工具的阶段，短暂停顿后继续输出。

这里有一个经验之谈：不要因为流式输出中某个停顿就误判为卡死。工具调用本身也是耗时的一部分，尤其是远程 SSE 链路，网络延迟加上工具执行时间，停顿一两秒非常正常。排查时先把日志打开，观察工具调用记录，再决定是否调整超时参数。如果你把超时调到 3 秒，远程 MCP 工具调用稍微慢一点就被断开，那问题其实是你自己的超时设置不合理。

5. 典型故障与排查技巧实录

5.1 SSE idle timeout 与代理断开

有一条非常典型的报错：stream disconnected before completion: idle timeout waiting for SSE。这句话的意思是：SSE 连接建立后，长时间没有新事件到达，服务端或中间代理判定为空闲连接，直接断开了。

原因通常是 Nginx 默认的 proxy_read_timeout 是 60 秒。当模型思考时间较长，或 MCP 工具执行超过这个时间，连接就会断。解决的思路很简单，但很多人忘了检查代理层：

location /sse { proxy_pass http://backend; proxy_set_header Connection ''; proxy_http_version 1.1; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_send_timeout 300s; }

关键点是关闭 proxy_buffering，确保事件流不被缓冲延迟。如果你没走 Nginx，直连 Spring Boot，那就检查客户端连接超时配置和服务端异步请求超时配置，把时间拉长到业务可接受的范围。我实测下来发现，大多数“流断了”都不是程序逻辑问题，而是中间某个超时默认值太小。排查这类问题，先定位是哪个环节断的，再对症下药。

5.2 stdio 进程秒退/工具不注册

stdio 模式下最常见的问题就是子进程没有起来。表现是：应用能启动，日志也没有明显报错，但工具注册列表是空的。排查顺序我建议从外到内：

1. 手动在命令行执行配置里的 command + args，看能不能正常跑。这一步能过滤掉命令写错、路径不存在、npx 网络下载失败等问题。
2. 检查 args 数组是否被 shell 拆词。Spring AI 的配置是参数数组，不要像 shell 一样自己拼字符串。
3. Windows 下检查是否写成了 npx.cmd。
4. 开启客户端调试日志，把 MCP 握手过程的细节打出来：

logging: level: org.springframework.ai.mcp: DEBUG

日志里一般能看到连接建立到哪一步失败。不要一上来就怀疑 Spring AI，先确认命令本身能跑。手动执行命令是最快的验证方式，因为你能直接看到 Node 进程是否启动、是否报错、是否进入等待状态。我在教同事排查时，第一步永远是“来，先在终端手跑一次”。

5.3 工具注册了却没被模型调用

比连接失败更让人崩溃的是：工具明明注册成功了，日志里能看到 Registered tool，但模型就是不调用，只会说“抱歉我没有这个能力”。

这种情况通常是模型的问题，不是 Spring AI 的问题。原因有三类：

第一，模型本身不支持工具调用，或当前接入的模型工具调用能力很弱。换一个能力强的模型立刻见分晓。第二，提示词不明确。你问“这个目录里有什么”，模型可以选择不调用工具，直接凭训练记忆给你编一个答案。建议把提示词改成“请使用 list_directory 工具查看 D:/mcp-workspace 目录，并基于工具返回结果回答”。第三，上下文里没有说明工具的存在。虽然 Spring AI 已经把工具描述注入到系统上下文了，但有些模型对工具描述的理解不敏感，显式点名工具往往更有效。

排查时打开工具调用相关日志，观察模型输出里是否出现 function call 类型的消息。如果根本没有，那就是选择环节出问题；如果有调用但执行失败，那就是执行链路问题。两条路径分开排查，别混在一起。我之前遇到过模型持续调用一个不存在的工具名，后来发现是因为 MCP 工具描述里参数名写得含糊，模型理解错了，改清晰描述后问题立刻消失。

5.4 自定义日志管理：MCP Server 端日志去哪了

这也是实际项目里绕不开的问题：生产环境要求日志统一走公司内部的日志框架，MCP Server 端的日志怎么接进来？

分两种情况。SSE 模式下，MCP Server 如果是 Spring Boot 应用本身，那它天然就是统一日志体系的一部分。你只管配置 Logback 或 Log4j2 的 logger 级别和 Appender 就行：

logging: level: org.springframework.ai.mcp.server: DEBUG org.springframework.ai.mcp.client: DEBUG

stdio 模式下，你依赖的是 Node 子进程，Spring AI 会把标准错误流 stderr 捕获并输出到应用日志里。你可以通过配置 Node 进程的环境变量来改变日志输出，更常见的做法是让 MCP Server 端把业务日志写到独立文件，Spring 侧只负责转发 stdout 协议流。这样两边日志互不干扰，排查问题时可以在文件里按时间戳对齐。

这里有个容易踩的雷：千万不要在 MCP Server 的 stdout 里打印任何日志。我见过有人在自定义 MCP Server 里顺手来了句 System.out.println，结果协议包被污染，客户端解析直接乱掉，工具调用连环失败。凡是日志，一律走 stderr 或独立文件。这个问题在本地开发时隐蔽性很强，因为 Spring Boot 控制台同时显示应用和子进程输出，很难察觉叠加,一旦切到生产环境用日志采集器收集 stdout，问题立刻爆炸。

结尾

最后聊点实际经验。把 MCP 跑通从来没难在“配置有多复杂”，而是“你以为连上了，其实工具没有真正可用”。我自己带过几个同事上手这一步，最快的二十多分钟就能真调 file 工具，卡住一个下午的，基本都在 npx 命令写错、Windows 不认 npx.cmd、或者模型根本不支持 function call 这三件事上。所以别急着上生产架构，先在本地用 stdio 方式把最小闭环打出来，确认日志里出现工具调用记录，再去研究 SSE、流式渲染、统一日志这些外围能力。另外一个小技巧：实验目录里少放点文件，把无关大文件清出去，既能避免模型把大文件内容整个塞进上下文导致 token 暴涨，也能让工具返回结果更简洁，排查问题时一眼看明白。这个习惯我到现在都保留着。