Spring AI 接入 MCP：DeepSeek 连接 Filesystem Server 读取本地文件

Spring AI 接入 MCPDeepSeek 连接 Filesystem Server 读取本地文件做 Tool Calling Demo 时我们通常会把工具直接写在 Java 应用里Tool(description查询订单)publicStringqueryOrder(StringorderId){returnorderService.query(orderId);}这种写法很适合接入自己项目里的业务方法。但如果工具来自外部系统比如文件系统、GitHub、数据库、浏览器、运维平台每个 AI 应用都重复写一套适配代码就会很累。MCP 要解决的就是这个问题外部工具怎么用统一协议接进 AI 应用。它不是替代 Tool Calling而是和 Tool Calling 配合Tool Calling模型怎么请求调用工具 MCP外部工具怎么标准化接进来这次只跑一条最小链路Spring AI 作为 MCP Client连接本地 Filesystem MCP Server让模型读取一个测试文件。先把这条链路跑通再去接 GitHub、数据库、浏览器这些 MCP Server就不会乱。注意这篇只演示本地测试目录。生产环境不要随便把真实目录暴露给模型。一、先把范围缩小Spring AI 里和 MCP 相关的写法不止一种Spring AI 做 MCP Client Spring AI 做 MCP Server stdio 连接本地 MCP Server SSE / Streamable HTTP 连接远程 MCP Server入门时不要全塞在一起。我们先选最容易跑通的一条Spring AI 做 MCP Client通过 stdio 连接本地 Filesystem MCP Server。整体关系是这样Spring AI 应用 → 启动并连接 Filesystem MCP Server → 获取 Server 暴露的文件工具 → 把工具交给模型 → 模型通过 Tool Calling 请求调用 → MCP Server 真正读取文件简单说MCP Client你的 Spring AI 应用 MCP Server外部工具服务这篇用现成的 Filesystem Server不从零写 Server。先把接入跑通。二、准备一个测试目录先准备几个前提你已经有一个能正常调用ChatClient的 Spring Boot 项目项目使用 Spring AI 1.1.7本机已经安装 Node.js 和npx当前模型支持 Tool Calling。这篇示例使用 DeepSeek模型用deepseek-v4-flash。如果你走的是第三方兼容网关要确认网关会不会完整透传tools参数和 tool call 响应。先建一个测试目录mkdir-p/tmp/spring-ai-mcp-demoechoHello from Spring AI MCP Demo/tmp/spring-ai-mcp-demo/test.txt先手动验证 Filesystem MCP Server 能不能启动npx-ymodelcontextprotocol/server-filesystem /tmp/spring-ai-mcp-demo如果看到类似输出说明本地 Server 能跑Secure MCP Filesystem Server running on stdio验证完可以停掉。真正接入 Spring AI 时Spring AI 会根据配置自动启动它。三、添加依赖pom.xml至少需要这几个依赖propertiesjava.version17/java.versionspring-ai.version1.1.7/spring-ai.version/propertiesdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependenciesdependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependencydependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-deepseek/artifactId/dependencydependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-client/artifactId/dependency/dependenciesspring-ai-starter-mcp-client负责把 Spring AI 应用变成 MCP Client。这篇连接的是本地 stdio Server。如果以后要接远程 MCP Server再考虑spring-ai-starter-mcp-client-webflux。四、配置 DeepSeek 和 MCPapplication.yaml这样写spring:application:name:spring-ai-mcp-demoai:model:chat:deepseekdeepseek:api-key:${DEEPSEEK_API_KEY}chat:options:model:deepseek-v4-flashtemperature:0.2mcp:client:type:SYNCstdio:connections:filesystem:command:npxargs:--y-modelcontextprotocol/server-filesystem-/tmp/spring-ai-mcp-demo启动前设置环境变量exportDEEPSEEK_API_KEY你的 API Key这段配置的关键点有三个使用 DeepSeek 作为聊天模型通过npx启动 Filesystem MCP Server只暴露/tmp/spring-ai-mcp-demo测试目录。如果用 IDEA 运行在 Run/Debug Configurations 里给启动配置加环境变量DEEPSEEK_API_KEY你的 API KeyWindows 上通常要用cmd.exe /c包一层command:cmd.exeargs:-/c-npx--y-modelcontextprotocol/server-filesystem-C:\tmp\spring-ai-mcp-demomacOS / Linux 按前面的写法即可。五、写一个测试接口新建McpControllerpackagecom.example.springaideepseekdemo.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.ai.tool.ToolCallbackProvider;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;RestControllerpublicclassMcpController{privatefinalChatClientchatClient;privatefinalToolCallbackProvidermcpTools;publicMcpController(ChatClient.Builderbuilder,ToolCallbackProvidermcpTools){this.chatClientbuilder.defaultSystem( 你是一个文件读取助手。 只能通过工具访问 /tmp/spring-ai-mcp-demo 目录。 当用户说 test.txt 或测试目录时都指 /tmp/spring-ai-mcp-demo。 不要请求访问 /、用户主目录、项目源码目录或其他目录。 ).build();this.mcpToolsmcpTools;}GetMapping(/ask)publicStringask(RequestParamStringquestion){returnchatClient.prompt().user(question).toolCallbacks(mcpTools).call().content();}}这里有个容易写错的点不要想当然写成McpClient.getTools(filesystem)。在 Spring AI 1.1.7 里MCP Client Starter 会把 MCP Server 暴露的工具转换成ToolCallbackProvider。ChatClient可以直接这样接.toolCallbacks(mcpTools)如果项目里还有其他ToolCallbackProviderBean构造方法注入时可能需要用Qualifier指定。这个最小 Demo 只有一个 MCP Provider可以直接注入。六、启动测试启动应用./mvnw spring-boot:run读取test.txtcurl--gethttp://localhost:8080/ask\--data-urlencodequestion帮我读取 /tmp/spring-ai-mcp-demo/test.txt 的内容如果模型选择了文件读取工具最终会返回类似test.txt 的内容是Hello from Spring AI MCP Demo也可以测试列目录curl--gethttp://localhost:8080/ask\--data-urlencodequestion列出 /tmp/spring-ai-mcp-demo 目录下有哪些文件如果日志里出现Access denied - path outside allowed directories不用慌。这说明模型请求了白名单之外的路径比如/。Filesystem MCP Server 拒绝了这次访问这是安全拦截不是 MCP 没接上。如果模型一直普通回答没有请求工具优先检查模型是否支持 Tool Calling DEEPSEEK_API_KEY 是否正确 中间网关是否透传 tools 参数先跑编译./mvnw clean compile-DskipTests然后启动应用请求/ask能读到Hello from Spring AI MCP Demo七、背后发生了什么业务代码看起来只有这一段chatClient.prompt().user(question).toolCallbacks(mcpTools).call().content();背后其实分成两条链路。应用启动时Spring AI 读取 application.yaml → 启动 Filesystem MCP Server → 建立 stdio 连接 → 获取 Server 的工具列表 → 转成 Spring AI 的 ToolCallback用户提问时用户提问 → 模型看到可用工具 → 模型判断要调用文件工具 → Spring AI 执行 ToolCallback → ToolCallback 通过 MCP 调用 Filesystem Server → Server 读取文件并返回结果 → 模型基于工具结果组织回答所以 MCP 和 Tool Calling 不是两套互斥方案MCP 负责把外部工具接进来 Tool Calling 负责让模型请求调用这些工具八、什么时候用 MCP如果只是当前项目里的几个业务方法直接写Tool更轻查订单 查物流 查库存这些能力本来就在当前应用里没必要为了 MCP 多绕一层。MCP 更适合工具要被多个 AI 应用复用 工具需要独立部署和维护 要接入现成的外部 MCP Server 工具很多不想每个应用都重复适配可以这样记Tool把当前应用里的方法暴露给模型 MCP把外部工具服务标准化接入应用Spring AI 不需要知道 Filesystem Server 内部怎么读文件只要按 MCP 协议连接它、拿到工具、执行工具调用就行。九、别忽略安全边界MCP 接入不难但安全边界一定要提前想清楚。Filesystem Server 会真正读写文件。入门 Demo 只暴露/tmp/spring-ai-mcp-demo不要暴露/ /Users/你的用户名 项目源码目录 .ssh 配置和密钥目录工具描述不是权限控制。真正的目录边界、权限校验、危险操作拦截都要在应用侧或 MCP Server 侧做。入门阶段建议只读文件、列目录。如果要开放写入、创建目录、移动文件至少要加用户权限校验 目录白名单 操作日志 二次确认 限流和超时还有一个常见误区MCP Server 能连上不代表模型一定会调用工具。模型会不会调用还取决于模型能力、工具描述、用户问题以及模型服务是否支持 Tool Calling。排查时分两步看先确认 MCP Server 能启动 再确认模型真的返回 tool call这两个问题不要混在一起。写在最后这篇文章跑通的是一条最小链路Filesystem MCP Server 暴露工具 → Spring AI MCP Client 连接 Server → MCP 工具转成 ToolCallbackProvider → ChatClient 把工具交给模型 → 模型通过 Tool Calling 请求调用 → Spring AI 通过 MCP 执行工具如果说Tool是把工具写在应用里那 MCP 就是把工具从应用里拆出去再用协议接回来。它的价值不在于“更高级”而在于工具可以独立维护多个 AI 应用可以复用外部工具生态可以标准化接入。但 MCP 只负责连接不负责替你做权限、业务规则和风险兜底。先用本地 Filesystem Server 跑通再考虑 GitHub、数据库、浏览器或公司内部系统。Agent 能力越多安全边界越要清楚。后续会继续更新 Spring AI、RAG、Memory、Tool Calling、MCP 等实战内容。