1. 为什么 Java 开发者需要关注 Spring AI 与 MCP如果你写过 Spring Boot大概率经历过这样的场景想让 AI 帮你读一下项目里的某个文件、查一下数据库、调一下内部接口结果发现模型只能空口说白话它根本碰不到你的真实环境。MCPModel Context Protocol就是来解决这件事的——它是一套开放协议把模型和外部工具、数据源之间的连接方式标准化你可以把它理解成AI 世界的 USB-C 接口。而 Spring AI 是 Spring 生态里专门做大模型集成的框架它把 MCP 客户端封装成了 Spring Boot Starter意味着你不需要手写协议解析、不需要自己管理 stdio 进程通信只要在application.yml里写几行配置就能让本地模型调用文件系统、数据库、地图等外部能力。这篇内容面向的是有 Java 基础、但没接触过 MCP 的开发者我会从依赖引入开始一步步带你跑通Spring AI MCP 调用文件系统工具的完整链路包括配置骨架、工具注册、端到端验证以及我实际踩过的几个坑。核心检索词先明确Spring AI MCP 是 Spring AI 对 MCP 协议的客户端实现能让你在 Java 项目里用注解和配置文件的方式接入 MCP Server它适合想给现有 Java 系统加 AI 工具调用能力的后端工程师也适合正在做 Agent 落地、需要标准化工具接入的团队。下面所有代码和配置都可以直接复制到你的工程里。2. 前置准备TaoToken 与本地模型环境在写代码之前有两件事需要先确认模型从哪来、MCP Server 怎么跑。模型这块我建议用 TaoToken 做统一入口。它的作用是让你用一套 API Key 就能切换不同模型不用每个厂商都去注册一遍。对于 Spring AI 项目来说你只需要把 base-url 指向 TaoToken 的 API 地址模型名换成你想要的即可。访问入口在这里官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址https://taotoken.net/api如果你只是想先跑通 MCP 链路用本地 Ollama 也完全可以我下面的示例会以 Ollama 为主因为不依赖网络、调试更快。等你验证通了再把模型换成 TaoToken 上的云端模型即可。MCP Server 这边你需要一个能提供工具的服务端。最省事的方式是用现成的 npm 包比如modelcontextprotocol/server-filesystem它提供文件读写、目录列举等工具。前提是你的机器上有 Node.js 和 npx 环境命令行执行npx -v能输出版本号就说明没问题。如果没有去 Node.js 官网下载 LTS 版本安装即可这一步不涉及任何特殊网络配置。另外确认一下 JDK 版本Spring AI 1.0.0-M6 要求 Java 17 及以上。如果你本地还是 Java 8需要先升级否则启动会直接报UnsupportedClassVersionError。3. 可复制配置pom 依赖与 application.yml 骨架3.1 Maven 依赖引入新建一个 Spring Boot 工程pom.xml里加上这几个关键依赖。注意 Spring AI 的版本要用 BOM 统一管理避免版本冲突project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdorg.yxy/groupId artifactIdspring-ai-mcp/artifactId version1.0-SNAPSHOT/version packagingjar/packaging properties java.version17/java.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version3.2.4/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope version3.2.4/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement /project这里有个细节spring-ai-ollama-spring-boot-starter没有写 version因为它由 BOM 统一管理。如果你用的是其他模型比如 OpenAI 兼容接口把 ollama starter 换成对应的即可。3.2 application.yml 配置配置文件分两块模型配置和 MCP 客户端配置。MCP 部分的关键是stdio模式它会以子进程方式启动 MCP Serverspring: application: name: spring-ai-mcp ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5-coder:7b mcp: client: enabled: true name: mcp-client version: 1.0.0 type: SYNC request-timeout: 30s stdio: servers-configuration: classpath:/mcp-servers-config.jsontype: SYNC表示同步调用模式适合大多数请求-响应场景。如果你要做流式或高并发可以改成ASYNC但对应的注入类也要换。3.3 MCP Server 配置文件在src/main/resources下新建mcp-servers-config.json内容如下。注意 Windows 和 Mac/Linux 的 command 写法不同{ mcpServers: { filesystem: { command: cmd, args: [ /c, npx, -y, modelcontextprotocol/server-filesystem, F:\\web ] } } }Mac 或 Linux 用户把command: cmd改成command: npx并去掉/c这个参数。最后的路径是你允许 MCP Server 操作的目录建议先用一个测试目录别直接指向项目根目录。4. 工具注册与端到端调用验证4.1 Controller 里注册 MCP 工具Spring AI 会自动把 MCP Server 提供的工具封装成SyncMcpToolCallbackProvider你只需要把它注入进来然后在构建 ChatClient 时通过defaultTools注册package org.yxy.controller; import jakarta.annotation.Resource; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.mcp.SyncMcpToolCallbackProvider; import org.springframework.ai.ollama.OllamaChatModel; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class OllamaController { Resource private OllamaChatModel ollamaChatModel; Resource private SyncMcpToolCallbackProvider toolCallbackProvider; GetMapping(/ai/ollama) public String ollama(RequestParam(value msg) String msg) { ChatClient chatClient ChatClient.builder(ollamaChatModel) .defaultTools(toolCallbackProvider.getToolCallbacks()) .build(); String content chatClient.prompt(msg).call().content(); System.out.println(content); return content; } }toolCallbackProvider.getToolCallbacks()返回的是一个ToolCallback列表每个元素对应 MCP Server 暴露的一个工具。你可以打个断点看一下数组内容里面会有read_file、write_file、list_directory、list_allowed_directories等方法。4.2 启动并验证启动 Spring Boot 应用然后浏览器访问http://localhost:8080/ai/ollama?msg帮我在F:\web目录下创建一个test-mcp文件夹第一次请求可能会慢一些因为要等 npx 下载并启动 MCP Server 子进程本地模型推理也需要时间。等几秒到几十秒你会看到返回结果。如果模型正确调用了create_directory工具去F:\web目录下就能看到新建的test-mcp文件夹。我实测下来用 qwen2.5-coder:7b 这个模型工具调用的准确率还不错但偶尔会出现模型说它创建了、实际没调用工具的情况。这时候你可以把请求写得更明确比如请调用工具在 F:\web 下创建 test-mcp 目录成功率会高很多。4.3 换成 TaoToken 云端模型如果你不想本地跑模型把application.yml里的 ollama 配置换成 TaoToken 的 OpenAI 兼容配置即可。先去 TaoToken 控制台创建一个 API KeyAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite然后把依赖换成spring-ai-openai-spring-boot-starter配置改成spring: ai: openai: base-url: https://taotoken.net/api api-key: 你的Key chat: options: model: 你想要的模型名MCP 部分的配置完全不用动工具注册代码也不用改。这就是 Spring AI 抽象层的好处——模型换了工具调用链路不变。5. 本篇常见错误排查启动报NoClassDefFoundError: SyncMcpToolCallbackProvider说明 MCP starter 没引入或者版本不对。检查spring-ai-mcp-client-spring-boot-starter是否在依赖里版本是否和 BOM 一致。MCP Server 启动失败日志里出现npx: command not foundNode.js 环境没装好或者 npx 不在 PATH 里。命令行执行npx -v确认Windows 用户注意cmd /c这个前缀不能少。工具调用返回空或者模型说我没有这个能力大概率是defaultTools没生效。检查toolCallbackProvider.getToolCallbacks()是否返回了非空数组可以在 Controller 里打印一下长度。如果长度为 0说明 MCP Server 没连上去看启动日志里有没有 stdio 连接错误。请求超时request-timeout: 30s对于本地小模型可能不够尤其是首次加载。可以调到60s试试。另外确认 MCP Server 配置的目录路径存在路径不存在也会导致工具初始化失败。Windows 路径转义问题JSON 里反斜杠要写成\\比如F:\\web。如果写成F:\webJSON 解析会报错。模型不调用工具直接编造答案这是小模型的通病。解决办法有两个一是换更大的模型二是把 prompt 写得更指令化明确要求必须调用工具。另外qwen2.5-coder系列对工具调用的支持比通用模型更好建议优先用 coder 版本。6. 下一步从跑通到落地跑通这个 demo 之后你可以沿着几个方向继续深入。一是多 Server 配置在mcp-servers-config.json里加多个 server比如同时接文件系统和数据库Spring AI 会把所有工具合并注册。二是异步模式把type改成ASYNC注入AsyncMcpToolCallbackProvider适合高并发场景。三是自定义 MCP Server用 Java SDK 写自己的工具服务端把公司内部接口暴露给模型。如果你在接入过程中遇到工具注册或模型调用的问题可以先去 TaoToken 的接入文档里对照配置接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型本身能不能正常对话可以用模型对话页面快速测一下模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite如果你打算把 MCP 用到长期的编码或 Agent 项目里建议了解一下 Coding Plan它在调用额度和模型切换上更适合持续开发场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite整个链路跑下来最花时间的其实不是写代码而是环境准备和排错。把 MCP Server 的日志打开遇到问题先看子进程有没有正常启动再看工具列表有没有注册成功最后才怀疑模型。这个排查顺序能帮你省掉大量试错时间。