1. 为什么要在 Spring AI 智能体里接 MCP 读本地文件如果你正在用 Spring AI 写智能体大概率会遇到一个很具体的需求让模型能读本地目录里的文件比如项目文档、日志、配置、Markdown 笔记然后基于这些内容回答问题。传统做法是自己写一堆Tool方法把FileReader、Files.walk包一层再手动注册到ChatClient。能跑但每换一个数据源就要重写一遍工具描述、参数 schema、错误处理全得自己维护。MCPModel Context Protocol解决的正是这件事。它把「模型怎么连数据源和工具」抽象成一套标准协议本地文件系统、数据库、远程服务都可以各自实现一个 MCP ServerSpring AI 应用作为 MCP Client 去发现并调用这些工具。你不再关心文件怎么读只关心「有哪些工具可用」剩下的交给协议。这篇要落地的链路是Spring AI 智能体 → MCP Client → 本地 filesystem MCP Server → 读取本地文件数据 → 模型基于文件内容回答。同时把模型调用通道统一到 TaoToken 的 Key 上这样你本地调试、换模型、跑 Agent 都不用改业务代码只改配置。适合已经写过 Spring Boot、想快速把 MCP 跑通、又不想在模型接入上反复折腾的开发者。我试过把模型 Key 散落在环境变量、application.yml、IDE 运行配置里最后自己都记不清哪个生效。统一到一个 Key 通道之后排障成本明显下降这也是下面配置骨架的出发点。2. TaoToken 前置统一 Key 与 API 通道在写 MCP 之前先把模型通道固定下来。TaoToken 提供统一的 API 入口Spring AI 侧只需要配置base-url和api-key两个值就能对接模型对话能力。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要先拿到一个 Key。进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后复制保存后面配置里会用到。这里有个概念要分清MCP 负责「工具和数据源」TaoToken 负责「模型调用通道」。两者是正交的。你完全可以用 MCP 读文件用 TaoToken 调模型互不干扰。很多新手会把这两件事混在一起以为接了 MCP 就不用管模型 Key 了其实 MCP Server 本身不调模型它只暴露工具。配置上我建议分两层一层是模型通道TaoToken一层是 MCP Server 启动参数。下面分别给出settings.json和config.toml两种常见形态的骨架你可以按自己项目实际用的配置文件选一种。3. 可复制配置settings.json 与 config.toml 骨架先看settings.json。这种形态常见于把 MCP Server 配置和模型配置放在一起管理的场景比如某些客户端或工具链会读这个文件来启动 MCP Server。核心是把 filesystem server 的启动命令、参数、以及模型通道的 base url 写清楚。{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/workspace/docs ], env: { MCP_LOG_LEVEL: info } } }, model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelName: claude-3-5-sonnet } }注意args最后那个路径就是 MCP Server 能访问的根目录它决定了智能体能读哪些文件。不要一上来就写/或整个用户目录权限太大调试时也容易误读无关文件。先限定到一个具体目录跑通再按需放宽。再看config.toml。如果你的项目用 TOML 管理配置等价骨架如下[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/workspace/docs] [model] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_name claude-3-5-sonnet两种配置的语义完全一致区别只是格式。关键点有三个command必须是本地能执行的命令args里的路径必须是绝对路径api_key用你刚才在控制台生成的那个。如果你把 Key 直接写进文件记得别提交到 Git用.gitignore排除或者改成读环境变量。Spring AI 侧对应的application.yml大致是这样把模型通道指向 TaoTokenspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-3-5-sonnet这里用${TAOTOKEN_API_KEY}从环境变量读比硬编码安全。启动前export TAOTOKEN_API_KEYsk-你的Key即可。4. 端到端验证一次本地文件检索配置写完必须验证。分两步先确认 MCP Server 能起来并列出工具再确认 Spring AI 智能体能通过 MCP 读到文件内容。第一步单独启动 filesystem server确认工具列表。在终端执行npx -y modelcontextprotocol/server-filesystem /Users/yourname/workspace/docs如果 Node 环境正常它会以 stdio 方式启动并等待输入。这一步能跑起来说明npx和包名没问题。如果卡住不动通常是网络拉包慢或者路径不存在。第二步在 Spring AI 里初始化McpSyncClient并列出工具。核心代码Bean(destroyMethod close) public McpSyncClient mcpClient() { var stdioParams ServerParameters.builder(npx) .args(-y, modelcontextprotocol/server-filesystem, /Users/yourname/workspace/docs) .build(); var mcpClient McpClient.sync( new StdioServerTransport(stdioParams), Duration.ofSeconds(10), new ObjectMapper()); var init mcpClient.initialize(); System.out.println(MCP Initialized: init); return mcpClient; }启动后控制台会打印初始化结果里面包含 server 信息和协议版本。接着把工具适配成 Spring AI 的 function callbackBean public ListMcpFunctionCallback functionCallbacks(McpSyncClient mcpClient) { return mcpClient.listTools(null) .tools() .stream() .map(tool - new McpFunctionCallback(mcpClient, tool)) .toList(); }然后注入到ChatClientvar chatClient chatClientBuilder .defaultFunctions(functionCallbacks) .build();第三步发一个真实问题让模型去读文件。比如目录里放一个notes.md内容是「本周待办修复登录超时」。然后提问String answer chatClient.prompt() .user(读取 notes.md告诉我本周待办是什么) .call() .content(); System.out.println(answer);成功的结果是模型先触发 function callMcpClient通过 stdio 把请求转给 filesystem serverserver 读取文件返回内容模型再基于内容生成回答控制台输出类似「本周待办是修复登录超时」。整个过程你不需要在业务代码里写任何文件读取逻辑。如果你想单独验证模型通道是否通可以先用模型对话页面发一条消息https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。通道正常再回来跑 MCP能快速区分是模型问题还是 MCP 问题。5. 本篇常见错排查报错一npx: command not found。说明本地没装 Node/npm。装完之后npm install -g npx再重试。这是最常见的第一个坑尤其在干净的容器或新机器上。报错二MCP 初始化超时。McpClient.sync的第二个参数是超时时间默认给 10 秒。如果npx首次拉包慢会超时。解决办法是先手动在终端跑一次npx -y modelcontextprotocol/server-filesystem path把包缓存下来再启动应用。报错三文件访问权限问题。在 IDE 里运行时进程工作目录可能不是你以为的那个目录导致相对路径解析错误。统一用绝对路径并且确认该路径对当前进程可读。如果路径写错server 会启动但工具调用返回空或报错。报错四模型不触发 function call。检查defaultFunctions是否真的注入了 callback 列表。如果列表为空说明listTools没拿到工具回到第二步看初始化日志。另外模型本身要支持 function calling选一个支持的工具调用模型。报错五Key 无效或 401。确认base-url是https://taotoken.net/api没有多余斜杠确认 Key 是从控制台新生成的、没有空格。如果还是 401去 API Keys 页面重新生成一个再试。报错六改了配置不生效。Spring Boot 配置有优先级环境变量、application.yml、IDE 运行配置可能互相覆盖。排查时打印实际生效的base-url别靠猜。6. 继续往下走Coding Plan 与接入文档跑通上面这条链路之后你手里就有了一个能读本地文件的 Spring AI 智能体。接下来通常会往两个方向走一是把它变成长期运行的编码助手或 Agent二是接入更多 MCP Server 扩展能力。如果你要做长期编码或 Agent 场景建议看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续调用、多轮工具编排的用法。接入细节和参数说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到协议或字段问题先查文档再动手改代码。最后一个实用建议把 MCP Server 的根目录当成「最小权限边界」来管理。每接一个新数据源先想清楚它该暴露哪个目录、哪些工具再写进配置。这样后面接数据库、接远程服务时权限模型是一致的排障也有迹可循。
