McpAgentExecutor + McpClient 实战:让 Agent 直接操作文件系统和数据库的配置骨架

发布时间:2026/11/16 3:46:49

McpAgentExecutor + McpClient 实战:让 Agent 直接操作文件系统和数据库的配置骨架 1. 从 HTTP 工具到本地资源Agent 能力边界的一次扩展上一篇我们用 McpManager 把 HTTP API 接进了 Agent模型能自主查公网 IP、天气这类网络服务。但有一类能力是 HTTP API 覆盖不了的读取服务器上的日志文件、查询本地 PostgreSQL 数据库、记住跨轮次的状态、操作 GitHub 仓库、执行浏览器自动化。这些能力对应的是 NPX MCP 服务器——由 MCP 官方或社区维护的独立进程通过 npx 一行命令启动暴露标准的 MCP 工具接口。McpAgentExecutor 和 McpClient 的组合就是让 Agent 直接操作文件系统和数据库的最小配置骨架。它适合已经配好 NPX MCP 服务器、希望 Agent 直接读写本地资源的 Java 开发者也适合做本地开发与自动化场景的同学。我试过把 filesystem 和 postgres 两个服务器同时挂到一个 Agent 上整个接入过程只改了一行 tools() 调用其余 LLM、系统提示、maxIterations、回调全部不动。这篇文章会把 config.toml / settings.json 骨架、CC Switch 接入 TaoToken 统一 Key 通道、以及一次文件读写加数据库查询的验证动作完整走一遍。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Agent 代码之前先把模型通道打通。TaoToken 提供统一的 Key 和 API 入口Java 侧只需要一个 base_url 和一个 api_key不用为每个模型单独维护一套凭证。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。如果你用 Claude Code 或类似的编码工具可以用 CC Switch 把 TaoToken 配成统一通道。CC Switch 的作用是管理多套 API 配置并快速切换把 TaoToken 的 Key 填进去之后所有走 Anthropic 协议的工具都能复用同一份凭证。对应的 deep link 是 ClaudeCodeAnthropic 配置页进去之后填 base_url 和 api_key 即可。拿 Key 的步骤很短登录后进控制台在 API Keys 页面创建一个新 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-agent-local方便后面审计。注意Key 只显示一次复制后立刻存进环境变量或本地配置文件不要硬编码进 Git 仓库。模型选择上示例用 qwen3.6-plustemperature 设 0f因为工具调用场景需要确定性输出温度高了模型容易在参数拼装上发散。如果你要长期跑编码或 Agent 任务可以看 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按额度套餐走比单次调用更划算。3. 可复制配置mcp.server.config.json 与 settings.json 骨架McpClient 在 Spring 启动时会根据 mcp.server.config.json 里的别名拉起对应的 NPX 进程。先给一份最小可用的 filesystem 配置{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /tmp ], env: { NODE_ENV: production } } } }这里的关键点是 args 最后那个路径/tmp它是 filesystem 服务器的访问边界。服务器只会在这个目录内做 list_directory、read_file、write_file、create_directory 等操作传系统根目录或含敏感文件的路径等于把整个磁盘交给模型务必传受限路径。接着加 postgres 服务器和 filesystem 并列{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp], env: { NODE_ENV: production } }, postgres: { command: npx, args: [ -y, modelcontextprotocol/server-postgres, postgresql://readonly_user:passwordlocalhost:5432/mydb ], env: {} } } }postgres 服务器的连接串里账号建议只给 SELECT 权限。Agent 拿到 query、list_tables、describe_table 三个工具后会自己拼 SQL 并执行如果账号有 DROP 或 UPDATE 权限一次误操作就可能改数据。只读账号是最低成本的保险。如果你用 CC Switch 管理配置settings.json 里对应的是通道切换部分把 TaoToken 的 base_url 和 api_key 写进去{ provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: qwen3.6-plus }apiKey 用环境变量占位实际运行时由 shell 注入。这样配置文件可以进版本库Key 不会泄露。4. 可复制代码McpAgentExecutor 挂载 McpClient配置就绪后Agent 层的代码和上一篇几乎一样唯一区别是 tools() 的第一个参数从 mcpManager 换成 mcpClient第二个参数从 default 换成服务器别名。Test public void mcpClientAgent() { McpAgentExecutor agent McpAgentExecutor.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(); ChatGeneration result agent.invoke(列出 /tmp 目录下的所有文件并告诉我有多少个文件); System.out.println(\n 最终答案 ); System.out.println(result.getText()); }McpClient 在启动时按别名 filesystem 拉起进程服务器启动后向外暴露一组标准工具list_directory、read_file、write_file、create_directory 等。McpAgentExecutor 拿到这份工具列表后转成 Function Calling Schema 注册给模型后续的工具选择和调用由模型自主完成。maxIterations 设 5 是给多步任务留余量比如读 config.yaml 并告诉我数据库地址会触发 list_directory 加 read_file 两次调用。换成 postgres 服务器时只改一行McpAgentExecutor agent McpAgentExecutor.builder(chainActor) .llm(ChatAliyun.builder().model(qwen3.6-plus).temperature(0f).build()) .tools(mcpClient, postgres) // 换成 postgres 服务器 .systemPrompt(你是一个数据库助手可以查询数据库中的表结构和数据。) .maxIterations(5) .build(); ChatGeneration result agent.invoke(查询 orders 表中最近 5 条记录);模型会根据问题自动选择 list_tables 或 describe_table 先探结构再拼 query 执行 SQL返回结果。整个过程不需要写任何 JDBC 代码。5. 验证请求一次文件读写加数据库查询先验证文件系统。在 /tmp 下放几个测试文件echo db_hostlocalhost /tmp/config.yaml echo 2024-01-01 INFO started /tmp/demo.log echo ticket-001 /tmp/ticket_result.txt然后跑 mcpClientAgent()控制台输出类似 Tool call: list_directory - {path: /tmp} Observation: {files: [ticket_result.txt, demo.log, config.yaml]} 最终答案 /tmp 目录下共有 3 个文件包括 ticket_result.txt、demo.log、config.yaml。模型拿到 list_directory 的返回值后直接统计文件数量并输出结论整个过程只需一次工具调用。如果任务更复杂比如读取 config.yaml 并告诉我其中的数据库地址模型会自动追加一次 read_file 调用不需要任何额外代码。再验证数据库。假设本地 PostgreSQL 有 orders 表跑 postgres 版本的 Agent输出类似 Tool call: list_tables - {} Observation: {tables: [orders, users, products]} Tool call: query - {sql: SELECT * FROM orders ORDER BY created_at DESC LIMIT 5} Observation: {rows: [{id: 1024, amount: 299.00, ...}]} 最终答案 orders 表最近 5 条记录如下...模型先探表结构再拼 SQL最后把结果整理成自然语言。整个链路里McpClient 负责进程管理和工具发现McpAgentExecutor 负责把工具注册给模型并驱动多轮调用。6. 本篇常见错排查npx 找不到或 Node.js 未安装。filesystem 和 postgres 服务器都通过 npx 启动本地必须有 Node.js。报错通常是npx: command not found或进程启动后立即退出。先跑node -v和npx -v确认再检查 mcp.server.config.json 里 command 字段是否写成了绝对路径。filesystem 报路径越界。如果模型尝试访问 /tmp 之外的文件服务器会返回权限错误。这是预期行为不是 bug。检查 args 里的路径参数确认它就是你希望 Agent 能碰的目录。不要把/或/home传进去。postgres 连接串格式错误。连接串必须是postgresql://user:passwordhost:port/dbname的完整格式缺一段都会导致服务器启动失败。密码里如果有特殊字符需要 URL 编码。另外确认数据库允许本地连接pg_hba.conf 里的认证方式要匹配。工具调用返回空或模型不调用工具。先看 onToolCall 回调有没有打印。如果没有说明模型没触发 Function Calling可能是 systemPrompt 太模糊或者 temperature 设得太高。把 temperature 降到 0fsystemPrompt 里明确写请直接执行操作。maxIterations 太小导致任务中断。默认值如果设成 1多步任务会在第一次工具调用后就停。文件读取加数据库查询这类任务建议至少设 5。如果任务特别复杂可以调到 10但要配合 onToolCall 日志观察是否有死循环。Key 或 base_url 配错导致 401。检查环境变量 TAOTOKEN_API_KEY 是否注入成功base_url 是否写成https://taotoken.net/api。如果用的是 CC Switch确认当前激活的 provider 是 taotoken。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明。7. 继续往下走统一通道与工具扩展McpAgentExecutor 加 McpClient 的接入方式和上一篇的 McpManager 版本几乎完全一样学习成本接近零。区别只在于工具来源HTTP API 用 McpManagerNPX 服务器用 McpClient。切换工具来源时Agent 层的代码只改一行这意味着你可以先用 McpManager 接 HTTP 工具快速验证业务逻辑确认效果后再把部分工具替换成更稳定的 NPX 服务器整个迁移成本极低。如果你需要同时使用 HTTP 工具和 NPX 服务器可以把两者合并到同一个 Agent 中McpAgentExecutor 支持多工具源注册。模型通道方面所有模型调用都走 TaoToken 统一 Key不用为每个模型单独维护凭证。想直接验证模型对话效果可以进模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试一轮长期跑编码或 Agent 任务走 Coding Plan 更省心。生产环境记得把 onToolCall 和 onObservation 两个回调接入日志系统完整记录每次文件读写或 SQL 执行满足合规审计要求。
延伸阅读

更多相关文章

2026/11/15 3:16:10

EmuELEC系统写入EMMC完整实操指南:告别TF卡,稳定运行游戏系统

1. 为什么非要把EmuELEC装进EMMC?先搞懂三个关键概念用TF卡玩EmuELEC的人,十有八九都经历过这几件事:游戏加载卡顿、系统莫名其妙掉配置、TF卡用了半年开始掉速,甚至有一次开机直接卡在logo界面,怎么拔插都没反应。我当…

2026/11/16 17:17:17

Terraform实战:在Ubuntu 22.04上用代码自动化管理AWS云资源

如果你还在用AWS控制台一个个点鼠标创建EC2、VPC、安全组,那你一定受够了那份繁琐。资源一多,除了手工重复劳动,最怕的就是改错配置后忘了改回去,结果月末账单出来的时候血压飙升。Terraform就是来解决这个问题的:它把…

2026/11/16 18:00:05

河南周口在哪考电工证值不值得考

河南周口在哪考电工证值不值得考 证书过期了不知道怎么复审延期?别急,这可能是你最头疼的问题。很多人在拿到电工证后,因为工作变动、转行或疏忽,一不留神就错过了复审时间,结果证书失效,不仅影响工作,还可能面临重新考证的麻烦。那么,…

2026/11/16 18:00:05

高压电工证工作日志怎么写?含金量高的证书别让有效期“掉链子”

高压电工证工作日志怎么写?含金量高的证书别让有效期“掉链子” 证书过期了不知道怎么复审延期,你是不是也遇到过这种情况?高压电工证作为特种作业人员的“通行证”,其含金量不言而喻,但很多人只关注怎么考,却忽略了怎么维护。一旦错过复审时间,不仅影…

2026/11/16 18:00:05

阿城在哪里考电工证啊 值不值得考

阿城在哪里考电工证啊 值不值得考 之前考的证在外省能不能转过来?这个事儿我太熟悉了,上周刚有位阿城的朋友找我,说他之前在外地考的低压电工证,现在想在阿城继续干电工作业,但不知道能不能转过来。我一看,他的证书信息在 特种作业操作证查询平台…

2026/11/16 17:55:05

万江哪里考电工证最快 全国通用电工证怎么考不被坑

万江哪里考电工证最快 全国通用电工证怎么考不被坑 你是不是也遇到过这种情况:听说电工证能全国通用,想找地方考,结果网上信息五花八门,要么是野路子培训,要么是高价代办,结果一不小心就踩坑了?特别是在万江,想找一个靠谱的报名点,既快又不被中介忽…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑