基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-16 23:57

用 ADK 快速接入 MCP 文件工具

dev.to · AI#MCP#Agent#Python
Editor brief · 编辑速览

示例通过 Google ADK 的 McpToolset 启动本地文件系统 MCP 服务,让 Agent 使用已有工具接口。代码用 tool_filter 限定目录浏览和文件读取能力,减少逐个编写工具包装的工作。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

AI 深度解读

给 Agent 接文件系统、GitHub、Slack,麻烦的往往不是调用模型,而是反复处理鉴权、参数定义和工具适配。作者的结论是:Google ADK 已经提供 MCP 客户端 McpToolset,接入现成服务,可以省掉一大块连接代码。

但这篇最值得读的并不是「20 行 Python」。它真正讲清了三个问题:工具怎样进入模型的调用范围,本地示例怎样迁到远程服务,以及为什么少写一行过滤配置,就可能让只负责读文件的 Agent 获得写文件的能力。

接上 MCP,究竟省掉了哪部分代码

MCP(Model Context Protocol)是一套暴露工具的标准。作者称,目前已有数千个 MCP server,覆盖 GitHub、Slack、Postgres、Google Maps 和文件系统等服务。过去需要逐个写 Python wrapper,现在可以复用服务端已经提供的工具接口。

这里有三个角色:MCP server 实际执行操作,McpToolset 负责连接、获取工具列表并转换成模型可调用的工具,ADK Agent 再决定调用哪个。模型看到的仍然是普通工具,不需要理解 MCP。

下面这段代码解决的是:让 ADK 启动一个本地文件系统服务,并只向 Agent 开放目录查看和文件读取。

from google.adk import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

files = McpToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/data"],
        )
    ),
    tool_filter=["list_directory", "read_file"],
)

root_agent = Agent(
    name="ops",
    model="gemini-flash-latest",
    instruction="You help the user explore files under /data. Read before you answer.",
    tools=[files],
)

要盯住 args 中的 /data 和 tool_filter:前者指定服务访问的目录,后者限定模型能调用的工具。

按原文,把文件保存成 ops/agent.py,执行 pip install google-adk,再运行 adk web。进入开发界面选择 ops,就能询问 /data 的内容。作者描述的运行结果是先调用 list_directory,再调用 read_file,根据读取结果回答。

首次启动时,npx 会下载服务包。作者遇到的启动挂起或 ConnectionError: Failed to create MCP session: Connection closed,归因于包拉取失败,建议先执行 npm install @modelcontextprotocol/server-filesystem,再把启动方式改为 command="node",参数改为 args=["./node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "/data"]。

这是一条排查线索,不能据此认定所有连接关闭错误都由下载失败造成。

从本地到部署,变的是连接方式

StdioConnectionParams 会启动子进程,通过标准输入、标准输出通信。本地试验很方便,但服务每增加一个副本,也会启动一份 MCP 子进程。作者因此建议,正式部署时连接已经运行的远程服务,使用 Streamable HTTP。

下面的代码展示了远程地址、Bearer 鉴权和两种超时配置:

import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

remote = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=os.environ["MCP_URL"],
        headers={"Authorization": f"Bearer {os.environ['MCP_TOKEN']}"},
        timeout=5,
        sse_read_timeout=300,
    ),
)

要注意最后两个参数:timeout=5 管连接和请求超时,sse_read_timeout=300 管流式响应可以保持多久。后者设置过短,耗时工具可能执行到一半就被中断。

两种连接可以同时交给一个 Agent,配置为 tools=[files, remote]。不过,远程示例没有设置 tool_filter,照搬之前仍要补上工具范围限制。

ADK 还支持反向暴露:从 google.adk.agents 导入 LlmAgent,从 google.adk.tools.mcp_tool 导入 to_mcp_server,通过 server = to_mcp_server(my_agent) 包装已有 Agent,再调用 server.run(transport="stdio")。外部 MCP host 看到的是代表整个 Agent 的一个工具,内部工具不会直接暴露。它适合把单一职责的 Agent 交给其他系统调用。

为什么工具白名单比接通更重要

作者实查发现,文件系统服务提供的是 14 个工具,而示例只需要 2 个。不加过滤,Agent 还能接触创建目录、编辑、移动、写入等操作。加上过滤后,get_tools() 返回恰好 2 个工具。

任务只需要读取,就只开放读取所需的工具。

这既缩小误操作范围,也减少工具描述带来的上下文开销。作者指出,工具名称、描述和 schema 都会进入模型上下文;多开放 40 个不用的工具,就会反复承担相应的 token 成本。不过,原文没有给出具体 token 数或费用对照。

还有一层风险叫工具投毒(tool poisoning):服务端可以在工具描述中夹带指令,例如诱导模型把配置文件内容发往某个地址。模型为了选择工具必须阅读描述,恶意内容也就进入了工作上下文。

作者给出的处理方式接近管理 npm 依赖:固定版本,至少人工读一遍工具描述,不要把未经检查的服务用 -y 直接带进生产环境;涉及真实数据时,优先使用自己或公司运行的服务。文件系统示例适合临时目录,不适合直接指向整个用户主目录。

白名单能缩小可调用范围,但不能证明获准工具的实现可信。一个名为读取的工具是否真的只读取,仍取决于服务端代码和运行权限。

我的判断

这篇的价值在于把接入流程和权限边界放在了一起。相比逐个写 wrapper,MCP 能复用工具发现和适配机制;但鉴权、分页、错误处理等复杂度并没有消失,其中一部分转移到了服务端。

作者声明所有代码都在 google-adk 2.14.1 上运行过。这能支持对应版本下的示例,却不能代替部署验证:Python、Node 版本,以及 MCP 服务包版本,原文没有交代清楚。

作者把 stdio 判为不适合生产,语气也偏绝对。每个副本各起子进程是否有问题,要看资源成本、隔离需求和运维方式。原文没有给出与 Streamable HTTP 的压测或成本对照,这部分应当视为部署经验。

我更认同作者最后划出的边界:MCP 解决工具连接,不负责工具失败后的恢复、重启后的状态保存,也不能保证修改提示词后行为依旧正确。接通服务只是开发起点。

能拿来做什么

  • 做文件问答或代码目录探索时,可以先用临时目录验证 list_directory 和 read_file,并检查 get_tools() 的实际结果,确认模型可调用范围符合预期。
  • 维护 Python Agent、同时复用 Node 工具服务的团队,可以用这个例子验证 MCP 接入链路,再决定是否替换现有 wrapper。
  • 将本地原型迁到远程服务时,应分别验证连接超时和长任务读取超时,并为远程 McpToolset 补上实际需要的工具白名单。
  • 修改提示词或升级依赖后,应重跑目录读取、工具失败和越权请求等关键场景;连接成功不能证明 Agent 的行为仍然正确。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
免费 AI 应用如何记账、限流与控预算
下一篇
Claude Code 用脚本批量编排工具调用

资讯速览

dev.to · AI · 2026-11-16 23:57

AI 评分 8.0 / 10

相关标签

#MCP#Agent#Python

继续阅读

  • TPU 强化学习如何消除训练推理数值偏差
  • 免费 AI 应用如何记账、限流与控预算
  • Claude Code 用脚本批量编排工具调用
  • 如何减少 Bedrock 主题拦截误判
  • 共享知识库如何实现租户级回答定制