用 ADK 快速接入 MCP 文件工具
示例通过 Google ADK 的 McpToolset 启动本地文件系统 MCP 服务,让 Agent 使用已有工具接口。代码用 tool_filter 限定目录浏览和文件读取能力,减少逐个编写工具包装的工作。
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 的行为仍然正确。