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 执行满足合规审计要求。
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 执行满足合规审计要求。
