McpAgentExecutor + McpClient：让 Agent 直接操作文件系统和数据库

标签JavaMCPNPXAgentj-langchainMcpAgentExecutor文件系统数据库前置阅读Java Agent 集成 MCP 工具协议 → McpAgentExecutor用几行代码让模型自主调用 HTTP 工具适合人群已配置好 NPX MCP 服务器希望 Agent 直接操作文件、数据库等本地资源的 Java 开发者一、HTTP 工具之外的能力上篇文章用McpManager把 HTTP API 接入了 Agent模型能自主查询公网 IP、天气等网络服务。但有一类能力是 HTTP API 覆盖不了的读取服务器上的日志文件、配置文件查询本地 PostgreSQL 数据库不想写 JDBC让 Agent 记住跨轮次的状态键值存储操作 GitHub 仓库、执行浏览器自动化这些能力对应的是NPX MCP 服务器——由 MCP 官方或社区维护的独立进程通过npx一行命令启动暴露标准的 MCP 工具接口。文章 08 已经介绍了如何用McpClient连接这些服务器本篇把它和McpAgentExecutor结合起来让模型自主调用这些工具。二、和上篇的唯一区别先看代码对比会非常直观。上篇HTTP 工具McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(...).tools(mcpManager,default)// 从 mcp.config.json 加载 HTTP 工具.systemPrompt(...).build();本篇NPX MCP 服务器McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(...).tools(mcpClient,filesystem)// 从 mcp.server.config.json 加载 NPX 服务器工具.systemPrompt(...).build();只改了一行把tools(mcpManager, default)换成tools(mcpClient, filesystem)。其余所有配置——LLM、系统提示、maxIterations、回调——完全不变。这正是McpAgentExecutor设计的价值所在工具来源可以随意切换Agent 层的代码不用跟着改。三、配置文件mcp.server.config.json描述要启动哪些 NPX 服务器{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/tmp],env:{NODE_ENV:production}}}}McpClient在 Spring 启动时会根据别名filesystem拉起这个进程服务器启动后会向外暴露一组标准工具list_directory、read_file、write_file、create_directory等。McpAgentExecutor拿到这份工具列表后转成 Function Calling Schema 注册给模型后续的工具选择和调用由模型自主完成。四、完整代码TestpublicvoidmcpClientAgent(){McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen3.6-plus).temperature(0f).build()).tools(mcpClient,filesystem)// 加载 filesystem 服务器的全部工具.systemPrompt( 你是一个文件管理助手可以浏览和读取 /tmp 目录中的文件。 请直接执行操作不要询问用户额外确认。 ).maxIterations(5).onToolCall(tc-System.out.println( Tool call: tc)).onObservation(obs-System.out.println( Observation: obs)).build();ChatGenerationresultagent.invoke(列出 /tmp 目录下的所有文件并告诉我有多少个文件);System.out.println(\n 最终答案 );System.out.println(result.getText());}五、执行效果 Tool call: list_directory - {path: /tmp} Observation: {files: [ticket_result.txt, demo.log, config.yaml, ...]} 最终答案 /tmp 目录下共有 8 个文件包括 ticket_result.txt、demo.log、config.yaml 等。模型拿到list_directory的返回值后直接统计文件数量并输出结论整个过程只需要一次工具调用。如果任务更复杂比如读取 config.yaml 并告诉我其中的数据库地址模型会自动追加一次read_file调用不需要任何额外代码。六、换一个服务器PostgreSQLfilesystem 只是众多 NPX MCP 服务器中的一个。把别名换成postgresAgent 就能直接查询数据库不用写任何 JDBC 代码在mcp.server.config.json中添加{mcpServers:{filesystem:{...},postgres:{command:npx,args:[-y,modelcontextprotocol/server-postgres,postgresql://user:passwordlocalhost:5432/mydb],env:{}}}}Agent 代码只改一处McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen3.6-plus).temperature(0f).build()).tools(mcpClient,postgres)// 换成 postgres 服务器.systemPrompt(你是一个数据库助手可以查询数据库中的表结构和数据。).maxIterations(5).build();ChatGenerationresultagent.invoke(查询 orders 表中最近 5 条记录);modelcontextprotocol/server-postgres暴露的工具包括query执行 SQL、list_tables列出所有表、describe_table查看表结构。模型会根据问题自动选择合适的工具拼装 SQL返回结果。七、生产环境注意事项路径安全filesystem 服务器默认能访问启动命令中指定的目录务必传入受限路径如/tmp或专用的工作目录不要传入系统根目录或含敏感文件的路径。数据库权限postgres 服务器使用的连接串对应的数据库账号应只赋予 SELECT 权限只读场景或明确需要的最小权限避免 Agent 误执行破坏性操作。审计日志onToolCall和onObservation两个回调在生产环境中不只是调试工具可以接入日志系统完整记录每次文件读写或 SQL 执行满足合规审计的要求。并发共享同一个McpClient实例对应同一个服务器进程可以被多个 Agent 共享。如果需要隔离不同 Agent 的访问路径可以在mcp.server.config.json中配置多个别名分别指向不同参数的同类服务器。八、总结McpAgentExecutor McpClient的接入方式和上篇的McpManager版本几乎完全一样学习成本接近零。区别只在于工具来源HTTP API 用McpManagerNPX 服务器用McpClient。切换工具来源时Agent 层的代码只改一行。这意味着你可以先用McpManager接 HTTP 工具快速验证业务逻辑确认效果后再把部分工具替换成更稳定的 NPX 服务器整个迁移成本极低。如果你的场景需要同时使用 HTTP 工具和 NPX 服务器下一篇会介绍如何把两者合并到同一个 Agent 中。 相关资源完整示例Article13McpClientAgent.java对应方法mcpClientAgent()服务器配置mcp.server.config.json常用 NPX MCP 服务器modelcontextprotocol/server-filesystem、server-postgres、server-memory、server-githubj-langchain GitHubhttps://github.com/flower-trees/j-langchainj-langchain Gitee 镜像https://gitee.com/flower-trees-z/j-langchain运行环境需配置阿里云 API Key示例模型qwen3.6-plus需本地安装 Node.js 以运行 npx