这段时间一直有人问我Spring AI 2 到底怎么接 MCP Server尤其是在真实项目里能不能让大模型直接读文件、列目录、搜文件。我自己的结论是能而且没那么玄乎。把 filesystem 这个官方 MCP Server 跑通分别用 stdio 和 SSE 两种传输方式再让 ChatClient 真正调用 read_file、read_directory 这些工具整个过程走一遍之后你对 MCP 的认知会比看十篇概念文章都清楚。这篇文章就当是 Spring AI 2 实战系列的第一篇。我不打算堆概念只讲怎么落地。如果你手里有一个 Spring Boot 项目想给大模型接上操作文件系统这类能力不管你做的是餐饮 SaaS 还是内部工具思路完全一样——无非是把 filesystem 换成你自己的业务工具。把链路跑通剩下的就是替换工具的问题。1. MCP 到底是什么filesystem MCP Server 解决的痛点1.1 先说说手动接工具为什么烦在 Spring AI 里给大模型加工具最原始的做法是手写 Function Calling每个方法都要定义描述、参数类型、必填项然后把这些注册成 JSON Schema 丢给模型。单个工具还好一旦工具数量超过五六个维护成本立刻上来了。新增一个参数忘记改 Schema模型就会一直传错参数。更麻烦的是这套注册逻辑是跟你的业务代码强耦合的换一个客户端、换一种协议又要重写一遍。MCPModel Context Protocol做的事情就是把工具暴露这件事标准化。它定义了一套基于 JSON-RPC 的通信方式服务器端提供工具客户端负责发现和调用。对大模型应用来说MCP Server 就是一个自适应工具箱模型通过协议自动知道你有哪些工具、每个工具接收什么参数调用完成后结果再通过协议回到模型手里。1.2 filesystem 官方示例为什么适合入门filesystem 是 MCP 官方仓库里的示例服务器相当于官方教学案例。它实现了对文件系统的基础操作工具覆盖日常开发 90% 的需求工具名作用关键参数read_file读取文件内容path、offset、limitread_directory读取目录列表pathsearch_files按文件名正则搜索目录path、patternget_file_info获取文件元信息pathwrite_file写入/覆盖文件path、contentedit_file编辑文件指定行path、editsmove_file移动/重命名文件source、destinationcopy_file复制文件source、destinationdelete_file删除文件pathlist_allowed_directories列出允许访问的目录无这些工具的共性很明确输入都是路径、输出都是结构化内容。对学习 MCP 来说filesystem 比那些封装好的业务服务器更透明——你能清楚看到每个工具被调用时发生了什么适合用来验证协议细节。1.3 两种传输方式怎么选MCP 客户端和服务器之间的通信方式主要有两种stdio客户端启动一个子进程通过子进程的标准输入和标准输出传输 JSON-RPC 报文。适合本地开发、单机场景Spring Boot 应用直接拉起一个 Node.js 子进程。SSE客户端通过 HTTP 连接到服务端暴露的 SSE 端点请求走普通 POST结果通过 SSE 流回。适合独立部署、远程调用、多客户端复用。stdio 的好处是零网络配置启动即用SSE 的好处是服务器可以单独运行不依赖父进程生命周期。我的建议是本地调试先用 stdio 跑通协议再切 SSE 验证远程链路。2. 环境与依赖Spring AI 集成 MCP 的选型与版本2.1 我用的技术栈这次示例的版本组合如下组件版本/说明JDK17Spring Boot3.4.xSpring AI2.x 主线通过 spring-ai-bom 引入Node.js20用于启动 filesystem 官方包MCP Java SDKio.modelcontextprotocol:java-sdk有一点必须先说清楚Spring AI 对 MCP 的支持分为两个方向别搞混。一个是把 Spring Boot 应用本身变成 MCP Server对外暴露工具另一个是让 Spring Boot 应用作为 MCP Client去连接外部 MCP Server。本文讲的是后者。你项目里的 AI 交互逻辑本质上就是大模型 工具注册 对话编排Spring AI 的 ChatClient 承担编排MCP Java SDK 承担协议层。2.2 Maven 依赖怎么加我建议用 spring-ai-bom 统一管理版本避免手工对齐各模块之间的兼容性。pom.xml 里核心依赖就三块dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdio.modelcontextprotocol/groupId artifactIdjava-sdk/artifactId version${mcp-sdk.version}/version /dependency /dependencies实际用的时候注意两点。第一spring-ai.version去 GitHub Releases 或 Maven Central 查最新稳定版不要用快照版。环境变量SPRING_AI_VERSION这种动态方式适合 CI本地开发写死更稳。第二io.modelcontextprotocol:java-sdk的版本和 Spring AI 内部自带的 MCP 模块版本尽量保持一致否则运行时可能出现NoSuchMethodError或类加载冲突。如果你发现 Spring AI 某个 starter 已经传递引入了 MCP 依赖可以显式声明覆盖版本或者用 exclusion 排掉再统一引入。我踩过一次版本不一致的坑表现是McpClient能编译通过但启动时抛ClassNotFoundException排查半天才发现是 BOM 和直接依赖打架。2.3 模型配置OpenAI 兼容接口都能用Spring AI 的spring-ai-starter-model-openai不止能连 OpenAI任何提供 OpenAI 兼容接口的模型都行。比如智谱配置方式如下spring: ai: model: openai: base-url: https://open.bigmodel.cn/api/paas/v4 api-key: ${ZHIPU_API_KEY} chat: options: model: glm-4-flash temperature: 0.3如果你用的模型不支持 OpenAI 兼容就换对应的 starter比如spring-ai-starter-model-qwen、spring-ai-starter-model-zhipuai。MCP 这块跟模型无关你只管把ChatModel注入进来就行。3. stdio 模式让 AI 直接操作本地目录3.1 原理启动一个子进程走标准输入输出stdio 模式的本质不复杂Spring Boot 应用通过命令行启动 filesystem MCP Server 这个子进程然后给它写入 JSON-RPC 请求从它的标准输出读 JSON-RPC 响应。子进程的生命周期由父进程管理Spring Boot 退出时子进程也会被回收。这里有一个关键认知filesystem MCP Server 本身就是一个独立的 Node.js 程序跑起来后它不认识 Spring Boot只知道我从 stdin 读消息往 stdout 写消息。MCP 协议就是双方沟通的语法。3.2 构建 stdio 模式的 McpClient先确保本机有 Node.js然后写一个 Spring 配置类创建 MCP 客户端Configuration public class McpStdioConfig { Bean(destroyMethod close) public McpSyncClient fileSystemMcpClient() { var parameters new StdioServerParameters.Builder() .command(npx) .args(--yes, modelcontextprotocol/server-filesystem, /tmp/mcp-test) .build(); var transport new SyncStdioServerTransport(parameters); McpSyncClient client McpClient.sync(transport).build(); client.initialize(); ListMcpSchema.Tool tools client.listTools(); log.info(MCP stdio client initialized, tools: {}, tools.stream() .map(McpSchema.Tool::name) .toList()); return client; } }注意上面代码里有个细节环境变量MCP_TIMEOUT默认是 1 分钟如果npx首次拉包很慢initialize()可能超时。你先在命令行手动跑一遍npx --yes modelcontextprotocol/server-filesystem /tmp/mcp-test看到MCP filesystem server running on stdio之类的输出后再回到 Spring Boot 里启动应用。这能帮你把npx 拉包慢和协议问题区分开。3.3 通过 Tool 暴露给 ChatClientMcpClient 拿到了工具列表但 ChatClient 不认识它。需要把调用 MCP 工具封装成 Spring AI 普通的工具方法。我习惯的做法是写一个工具服务类Service public class FileSystemMcpTools { private final McpSyncClient mcpClient; public FileSystemMcpTools(McpSyncClient mcpClient) { this.mcpClient mcpClient; } Tool(description 读取指定目录下的文件列表) public String readDirectory(String path) { var request new CallToolRequest(read_directory, Map.of(path, path)); CallToolResult result mcpClient.callTool(request); return extractText(result); } Tool(description 读取指定文件的全部文本内容可指定偏移量和长度限制) public String readFile(String path, Integer offset, Integer limit) { MapString, Object args offset null limit null ? Map.of(path, path) : Map.of(path, path, offset, offset, limit, limit); CallToolResult result mcpClient.callTool(new CallToolRequest(read_file, args)); return extractText(result); } private String extractText(CallToolResult result) { if (result null || result.content() null) { return ; } return result.content().stream() .map(String::valueOf) .collect(Collectors.joining(\n)); } }然后在ChatClient的构建阶段把工具注册进去Bean ChatClient chatClient(ChatClient.Builder builder, FileSystemMcpTools tools) { return builder .defaultSystem(你是一个能操作本地文件系统的助手只使用提供的工具不编造结果。) .defaultTools(new ToolCallbackProvider[]{ MethodToolCallbackProvider.from(tools) }) .build(); }3.4 实测一把让 AI 自己读文件准备测试目录和文件mkdir -p /tmp/mcp-test echo hello spring ai mcp /tmp/mcp-test/welcome.txt启动 Spring Boot 应用然后调用String answer chatClient.prompt() .user(请读取 /tmp/mcp-test/welcome.txt 的内容并用中文告诉我里面写了什么) .call() .content();正常情况下模型先请求调用read_fileSpring AI 执行本地工具方法方法内部通过 MCP 协议把请求发给 filesystem 子进程子进程返回文件内容最终模型生成回答/tmp/mcp-test/welcome.txt 的内容是hello spring ai mcp。这个过程中你可以在日志里看到工具调用的痕迹——read_file的参数path/tmp/mcp-test/welcome.txt以及返回结果。3.5 stdio 模式最容易踩的坑Windows 下的命令名是npx.cmd不是npx。直接用npx会报CreateProcess error2, 系统找不到指定的文件。Docker 容器跑项目时容器里必须装 Node.js而且要注意 npx 的缓存目录权限。很多人本地好好的一上容器就报无法下载包基本都是容器基础镜像没带 Node。文件系统权限。filesystem server 启动时指定的参数就是允许访问的根目录列表。比如你只给了/tmp/mcp-test那模型要读/etc/passwd就会被拒绝这个拒绝不是 Spring Boot 干的是 MCP Server 干的。这个设计其实是优点它等于给大模型的文件访问划了边界。子进程退出后客户端没有感知。如果你手动把 filesystem 进程杀了再调用工具会拿到一个诡异的空响应。我建议在配置类里给McpSyncClient加一个健康检查或者干脆把destroyMethod close配上让 Spring 容器负责回收。4. SSE 模式远程调用 filesystem 服务的正确姿势4.1 为什么需要切到 SSEstdio 模式虽然简单但限制也很明显filesystem Server 必须跟着 Spring Boot 应用跑在同一台机器上子进程生命周期受父进程影响多客户端没法共享同一个 Server 实例。一旦你需要把 MCP Server 独立部署或者让多个后端服务共享同一个文件访问能力SSE 就是更合适的选择。SSE 模式下filesystem Server 作为独立进程跑在某台机器上监听 HTTP 端口。Spring Boot 应用通过 HTTP 连接到它暴露的 SSE 端点。这个模式也是安卓这类移动端场景唯一可行的方案——你总不能在手机 App 里塞一个 Node 子进程吧。4.2 先把 filesystem Server 以 SSE 方式启动官方 npm 包默认跑的是 stdio。要以 SSE 方式启动需要给它显式指定 HTTP 端口。不同小版本参数略有差异我这边能跑的命令是这样npx --yes modelcontextprotocol/server-filesystem --port 8080 /tmp/mcp-test启动后服务端会监听 8080 端口。连接地址一般是http://localhost:8080/mcp旧版本是http://localhost:8080/sse。以服务端启动日志里实际输出的路径为准。如果--port参数不识别说明这个版本的官方包没有内置 HTTP 传输需要自己在外面套一层 SSE 网关。不用纠结直接换回npx提供的原生参数或者用 MCP 官方的 TS SDK 写一个十行左右的包装脚本。4.3 Spring Boot 侧构建 SSE 客户端SSE 模式下Spring Boot 侧用HttpSseClientTransportConfiguration public class McpSseConfig { Bean(destroyMethod close) public McpSyncClient sseFileSystemMcpClient() { HttpSseClientTransport transport HttpSseClientTransport .builder(http://localhost:8080/mcp) .build(); McpSyncClient client McpClient.sync(transport).build(); client.initialize(); ListMcpSchema.Tool tools client.listTools(); log.info(MCP SSE client initialized, remote tools: {}, tools.stream() .map(McpSchema.Tool::name) .toList()); return client; } }注意区分SSE 模式下 Spring Boot 应用是纯客户端不维护 filesystem Server 的生命周期。你需要另外想办法保证那台机器上的 filesystem Server 在运行——systemd、docker、k8s 都行。这也意味着文件目录的权限边界完全由独立那个进程的启动参数决定。4.4 SSE 连接时的 idle timeout 问题这是 SSE 模式最容易踩的大坑现象非常具体日志里出现stream disconnected before completion: idle timeout waiting for sse或者类似的Idle timeout报错。原因分三类模型思考耗时太长。MCP 客户端发完请求后会维持一条 SSE 长连接等待服务端推送结果。如果模型本身慢或者中间有网络代理nginx、云负载均衡连接长时间没有数据传输网关会认为连接已死主动掐掉。MCP Server 没有发心跳。有些 SSE 实现只在有数据时才写响应空闲时没有任何 keep-alive。一旦这个空闲时间超过代理的超时阈值连接就被断了。客户端 timeout 设置过小。Spring Boot 侧如果给 HTTP 客户端设置了太短的 read/connect timeout也会出现类似情况。解决办法从易到难先调整代理超时。如果用 nginx把proxy_read_timeout调大比如 300 秒。给 MCP Server 或传输层加心跳机制。MCP 规范里允许服务器发送ping事件确保连接是活跃的。Spring Boot 侧构建RestClient时把readTimeout放宽比如 120 秒起步。如果模型经常一次性思考很久考虑把单次调用改成流式输出让数据持续流动避免长空闲。说实话这个坑不是 Spring AI 独有的任何通过 SSE 调大模型都会遇到。你只要记住一个原则SSE 长连接的生命周期不仅仅是建立连接那一瞬间整个等待响应期间连接都必须保持活跃。4.5 验证 SSE 调用正常切到 SSE 模式后前面的Tool工具类不需要改因为McpSyncClient接口一致。只改配置类里注入的 Bean 实现即可。你只需要重新启动 Spring Boot 应用确认日志里输出的工具列表和 stdio 模式一致然后重复对话测试String answer chatClient.prompt() .user(请列出 /tmp/mcp-test 目录下的所有文件) .call() .content();如果能正常返回目录列表就说明 SSE 链路已经通了。5. 真调工具的完整链路从 ChatClient 到工具返回值5.1 一次工具调用的完整时序很多人以为模型直接把工具结果告诉你就完了实际上链路比这个长。我这里把一次成功的工具调用拆开来看用户输入问题Spring AI 把messages连同当前可用的工具列表一起发给大模型。模型分析问题后返回一个tool_call请求内容包含要调用的工具名比如read_file和参数比如path/tmp/mcp-test/welcome.txt。注意这一步模型并不真正读取文件它只是想要读取。Spring AI 收到tool_call查找本地注册的工具找到FileSystemMcpTools.readFile方法用反序列化后的参数调用它。你的工具方法内部执行mcpClient.callTool(...)把请求通过 stdio 或 SSE 传给 filesystem MCP Server。filesystem Server 执行read_file把文件内容打包成 MCP 协议的CallToolResult返回给 Spring Boot。你的工具方法把结果转成字符串返回给 Spring AISpring AI 把它作为一条tool消息发给模型。模型拿到工具结果生成最终回答。关键点在第 4 步mcpClient.callTool之前模型已经完成了选择工具这个决策工具执行成功后模型只是看到了结果再组织语言。所以你在日志里会看到两次模型请求一次带 tool_call一次带 tool 结果。5.2 返回值格式与截断处理MCP 的CallToolResult里包含一个content列表read_file这类工具的返回内容是文本类型的。我在工具类里写的extractText就是把content列表拼成字符串。但有个现实问题大文件会让返回内容大到超出模型上下文窗口。filesystem 的read_file支持offset和limit你可以自己限制读取大小另外在Tool方法内部做一个防御性的截断private static final int MAX_RESULT_LENGTH 8000; private String extractText(CallToolResult result) { if (result null || result.content() null) { return ; } String text result.content().stream() .map(String::valueOf) .collect(Collectors.joining(\n)); if (text.length() MAX_RESULT_LENGTH) { return text.substring(0, MAX_RESULT_LENGTH) \n...内容过长已截断; } return text; }很多项目踩坑都是从模型答非所问开始的排查到最后发现是工具返回了一整份 5MB 的日志文件模型上下文直接爆了。给工具返回值加上限是生产环境必须做的事。5.3 多目录、多实例怎么处理filesystem Server 启动时允许多传几个目录npx --yes modelcontextprotocol/server-filesystem /data/logs /data/backup /tmp/mcp-test这样模型能访问多个目录而list_allowed_directories工具会把这些目录暴露给模型让模型自己判断路径是否合法。Spring Boot 侧你不需要改动任何代码因为工具列表里始终有list_allowed_directories。如果你需要连接多个不同的 MCP Server比如一个 filesystem、一个数据库那就分别创建两个McpSyncClientBean然后用CompositeToolCallbackProvider把它们聚合起来注册给ChatClient。注意每个 Bean 的destroyMethod和Qualifier要配好不然 Spring 容器关闭时会报重复关闭的警告。6. 生产落地要处理的几件事日志、超时与前端渲染6.1 MCP 日志级别怎么调MCP 客户端默认输出大量 DEBUG 日志因为协议交互本身非常频繁。开发阶段你可以打开看工具调用的参数和返回值logging: level: io.modelcontextprotocol: DEBUG但生产环境不建议开 DEBUG。一是日志量太大二是工具参数里可能包含文件路径、文件内容等敏感信息。我的习惯是生产环境调到WARN只在出问题时临时开 DEBUG 排查。如果你完全不想管 MCP 内部日志只想看自己的业务日志那就保持默认Spring AI 的Tool执行本身会通过工具调用链记录在业务日志里。6.2 用自定义日志管理把请求串起来自定义日志管理这句问的人很多核心诉求其实就一个一条用户请求从进来到最终返回能不能在日志里连续追到。做法很简单利用 SLF4J 的 MDC。在 Controller 入口处生成 traceIdString traceId UUID.randomUUID().toString(); MDC.put(traceId, traceId); try { // 调用 chatClient } finally { MDC.remove(traceId); }然后 logback 的 pattern 里加一行pattern%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} [%X{traceId}] - %msg%n/pattern这样日志里每一行都会带上 traceId。MCP 客户端内部的日志也会用这个 traceId因为它在同一个线程的执行链路里。排查问题时 grep traceId 就能把用户提问 - 模型 tool_call - MCP 调用 - 工具结果完整串起来。6.3 配合前端 SSE 流式渲染与 abort如果你用 Spring AI 的ChatClient接口层可以直接返回FluxServerSentEventString前端拿到的是一个真实的 SSE 流逐字渲染模型输出。GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxServerSentEventString chatStream(RequestParam String prompt) { return chatClient.prompt() .user(prompt) .stream() .content() .map(content - ServerSentEvent.builder(content) .event(message) .build()); }前端如果只是展示用EventSource就够了如果要做停止生成这种交互EventSource.close()可以断流但如果你想在服务端也感知到中断并取消模型调用就得用fetch ReadableStream AbortControllerconst controller new AbortController(); fetch(/chat/stream?prompt encodeURIComponent(prompt), { signal: controller.signal, headers: { Accept: text/event-stream } }); // 点击停止 controller.abort();这里有个细节光调abort()只是前端断开了Spring Boot 后端那条流还在跑模型调用没有真正取消。想彻底取消需要结合响应式编程的onCancel回调或者在前端断开后通过 Spring AI 的取消机制中断上游流。如果你的模型服务按 token 计费这一步能省不少钱。6.4 安卓等移动端怎么办热词里出现安卓 stdio我干脆说透移动端不要碰 stdio。三个原因stdio 需要本地启动一个子进程安卓 App 没有这个权限模型也不应该内置 Node.js 运行时。移动端直接连接 MCP Server 会把 API Key、允许访问的目录等敏感配置暴露在客户端等于把文件系统权限交给了一台不可信设备。移动端网络环境复杂长连接容易被系统回收。正确姿势是移动端只连你自己的后端服务后端把 MCP Client 封装成一个带鉴权的 HTTP 接口。这样移动端拿到的是上传一段文本返回一个结果完全不需要理解 MCP。6.5 关于超时与并发我的最终建议stdio 模式适合开发、单机验证、脚本任务SSE 模式适合生产、跨机、移动端。所有涉及 SSE 的链路把空闲超时至少设到 120 秒以上。如果你在 Spring Boot 里自己管理McpSyncClient记得设置合理的requestTimeout。MCP Java SDK 的连接超时默认偏保守生产环境你会希望放宽一点。并发调用同一个McpSyncClient时注意同步客户端不是无限并发。真正的高并发场景建议用异步客户端McpAsyncClient或者做连接池不然 MCP 层会成为瓶颈。最后再分享一个小习惯跑通这套链路之后我给自己定了个规矩先用命令行手动跑一遍 MCP Server确认它能启动、能响应再写 Spring Boot 代码。这个习惯帮我把是不是协议问题从是不是代码问题里剥离出来。比如npx拉包失败、端口被占用、目录权限不对这些在命令行里一眼就能看到根本不用等 Spring Boot 启动后从日志里猜。你如果第一次接 MCP强烈建议也这么做。另一个我觉得很值的小技巧工具类里加一个listAllowedDirectories的Tool方法直接调用 MCP 的list_allowed_directories。这样大模型遇到这个文件能不能读的疑问时可以先自查权限边界而不是盲目尝试后报错。模型判断路径合法性的准确率会明显提高交互也自然很多。