| name | Dynamic MCP Loader |
| description | 动态 MCP 工具加载器，支持运行时连接远程 HTTP/SSE MCP 服务或启动本地 MCP 进程，让 Agent 根据需求即时扩展能力。适用于用户提到不熟悉的 MCP 服务时，通过搜索发现连接方式后动态加载。 |
Dynamic MCP Loader
概述
Dynamic MCP Loader 是一个元工具（Meta-Tool），赋予 Agent "自主扩张能力"。
它允许 Agent 在运行时动态加载新的 MCP 工具，而无需重启服务或修改配置文件。Agent 可以：
- 通过 Web 搜索发现 MCP 服务的连接方式（URL 或 npx 命令）
- 调用
connect_mcp 工具动态挂载该服务
- 立即使用新加载的 MCP 工具完成用户任务
核心优势：实现"Just-in-Time Tooling"（即时工具化）模式，Agent 不再需要背负几百个工具运行，而是按需"下载"技能。
何时使用此 Skill
触发场景：
- 用户提到某个 MCP 服务名称（如 "用 context7 查文档"、"用 brave search"）
- 用户要求使用特定功能但当前工具列表中没有对应工具
- 用户明确要求"安装"或"连接"某个 MCP Server
典型工作流：
用户请求 → Web Search 查找连接方式 → connect_mcp 动态加载 → 使用新工具
核心工具
connect_mcp
功能：全能型 MCP 加载器，支持远程和本地两种模式。
参数说明：
| 参数 | 类型 | 必需 | 说明 |
|---|
mode | "remote" 或 "local" | 是 | 连接模式 |
source | str | 是 | 远程模式填 URL，本地模式填基础命令（如 npx） |
args | List[str] | 本地模式必需 | 命令参数列表 |
env_vars | Dict[str, str] | 否 | 本地模式专用，环境变量（如 BRAVE_API_KEY） |
api_key | str | 否 | 远程模式专用，API Key 用于服务认证（如 Context7） |
返回值：执行结果信息字符串
使用指南
模式 A：远程 HTTP/SSE 服务
适用场景：MCP 服务以 HTTP 或 Server-Sent Events (SSE) 方式提供。
执行步骤：
- 通过搜索获取 MCP 服务的 URL
- 调用
connect_mcp，mode="remote"，source 填写 URL
- ADK 会自动连接并提取工具定义
示例 1：无需认证的远程服务
用户请求："连接公开的 MCP 服务"
Tool: connect_mcp(
mode="remote",
source="https://example.com/mcp"
)
Result: "[Success] remote MCP 工具加载成功！"
示例 2：需要 API Key 认证的远程服务（Context7）
用户请求："用 context7 查一下 fastmcp 库的最新版本，我的 API Key 是 ctx7sk-xxxxx"
Step 1: Web Search
Tool: web_search("context7 mcp server url")
Result: "Context7 MCP is available at https://mcp.context7.com/mcp"
Step 2: Dynamic Load with API Key
Tool: connect_mcp(
mode="remote",
source="https://mcp.context7.com/mcp",
api_key="ctx7sk-xxxxx"
)
Result: "[Success] remote MCP 工具加载成功！"
Step 3: Use New Tool
Tool: resolve_library_id(library_name="fastmcp")
Tool: query_docs(library_id="/...", query="latest version")
重要说明：
- Context7 使用自定义认证 header
CONTEXT7_API_KEY（非标准 Bearer Token）
- API Key 格式：
ctx7sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- 工具会自动检测
context7.com 域名并使用正确的 header 名称
模式 B：本地进程启动
适用场景：MCP 服务需要通过 npx、python 等命令在本地启动。
执行步骤：
- 通过搜索获取启动命令（如
npx -y @modelcontextprotocol/server-git）
- 将命令拆解为
command 和 args 列表
- 调用
connect_mcp，mode="local"
- 如果需要 API Key，通过
env_vars 传入
示例 1：Git MCP
用户请求："帮我启用 git 的 mcp 工具"
Step 1: Web Search (如果不知道启动方式)
Tool: web_search("modelcontextprotocol git server npx")
Result: "Run using: npx -y @modelcontextprotocol/server-git"
Step 2: Dynamic Load
Tool: connect_mcp(
mode="local",
source="npx",
args=["-y", "@modelcontextprotocol/server-git"]
)
Result: "[Success] local MCP 工具加载成功！"
Step 3: Use New Tool
Tool: git_status()
Tool: git_log(limit=10)
示例 2：Brave Search MCP（需要 API Key）
用户请求："用 Brave Search 的 MCP，我的 Key 是 BS-xxxxx"
Step 1: Web Search
Tool: web_search("brave search mcp server installation")
Result: "npx -y @modelcontextprotocol/server-brave-search"
Step 2: Dynamic Load with Env Vars
Tool: connect_mcp(
mode="local",
source="npx",
args=["-y", "@modelcontextprotocol/server-brave-search"],
env_vars={"BRAVE_API_KEY": "BS-xxxxx"}
)
Result: "[Success] local MCP 工具加载成功！"
Step 3: Use New Tool
Tool: brave_web_search(query="AI news today")
参数构造技巧
关键点：从搜索结果的字符串命令转化为结构化参数。
命令拆解规则
原始命令：npx -y @modelcontextprotocol/server-sqlite --db-path ./data.db
拆解为：
mode="local"
source="npx"
args=["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]
注意事项：
args 必须是列表，不能是字符串- 每个参数和值都是独立的列表项
- 如果用户提供了具体文件路径，替换掉搜索结果中的示例路径
环境变量处理
何时使用 env_vars：
- MCP 文档提到需要设置环境变量（如
BRAVE_API_KEY, OPENAI_API_KEY）
- 用户明确提供了 API Key
示例：
env_vars={
"BRAVE_API_KEY": "用户提供的Key",
"DEBUG": "true"
}
安全机制
1. 命令白名单
本地模式仅允许以下基础命令：
npx, uvx: Node.js 包管理工具node: Node.js 运行时python, python3: Python 解释器
拒绝示例：
connect_mcp(mode="local", source="rm", args=["-rf", "/"])
2. 参数注入防护
禁止参数中包含以下字符：
- 管道符
|
- 重定向
>, <
- 命令分隔
;, &
- 命令替换
`, $(
拒绝示例：
connect_mcp(mode="local", source="npx", args=["-y", "package; rm -rf /"])
3. 智能去重
防止重复加载同一服务：
- 远程模式：对比 URL（忽略末尾斜杠）
- 本地模式：对比
command + args 完全匹配
示例：
connect_mcp(mode="remote", source="https://mcp.context7.com/mcp")
connect_mcp(mode="remote", source="https://mcp.context7.com/mcp/")
故障排查
常见问题
问题 1：[System] 找不到命令 'npx'
原因：系统未安装 Node.js。
解决：提示用户安装 Node.js，或使用 bash skill 先执行 node --version 确认环境。
问题 2：[Error] 加载 MCP 失败: Connection timeout
原因：
- 远程模式：URL 错误或服务不可用
- 本地模式：NPM 包下载超时（首次运行需要下载）
解决：
- 检查网络连接
- 确认 URL 是否正确
- 本地模式：等待更长时间或提示用户手动预安装包
问题 3：工具加载成功但 Agent 没有调用新工具
原因：ADK 的工具列表更新需要在下一轮对话时生效。
解决：确保 connect_mcp 成功返回后，Agent 在下一次思考时会自动看到新工具。如果仍未调用，可能是工具描述不够清晰或用户需求表述不明确。
进阶用法
结合 Bash Skill 预检查环境
最佳实践：在动态加载前，先用 bash skill 确认环境。
Step 1: Environment Check
Tool: bash(command="node --version", timeout=5)
Result: "v20.10.0"
Step 2: Install if Needed
Tool: bash(command="npm install -g @modelcontextprotocol/server-git", timeout=60)
Step 3: Dynamic Load
Tool: connect_mcp(mode="local", source="npx", args=["-y", "@..."])
会话生命周期管理
重要提示：
- 动态加载的 MCP 工具仅在当前会话有效
- 用户的每个会话都有独立的
agent 实例，修改 agent.tools 不会影响其他用户
- 会话结束后，本地启动的进程会被自动清理（由 ADK 的
McpToolset 管理）
探索新 MCP 服务
通用流程模板：
User: "我想试用一个叫 [SERVICE_NAME] 的 MCP 工具"
Agent 执行:
1. web_search("[SERVICE_NAME] mcp server installation")
2. 分析搜索结果，识别连接方式
3. 如果是 URL → connect_mcp(mode="remote", source="URL")
4. 如果是命令 → 拆解后 connect_mcp(mode="local", ...)
5. 等待工具加载成功提示
6. 探索新工具的功能并完成用户任务
系统提示词建议
为了让 Agent 正确使用此 Skill，建议在 System Prompt 中添加：
### 动态 MCP 能力扩展
你可以使用 `connect_mcp` 工具来扩展你的能力。使用步骤：
1. **先搜索**：使用搜索引擎查找目标 MCP 的安装或连接方式。
2. **后连接**：
- **远程服务**（HTTP URL）→ `connect_mcp(mode="remote", source="URL")`
- **本地包**（npx/python 命令）→ `connect_mcp(mode="local", source="npx", args=[...])`
3. **参数构造**：
- 将搜索到的命令字符串拆解为列表
- 例如：`npx -y pkg arg` → `args=["-y", "pkg", "arg"]`
- 如果需要 API Key，通过 `env_vars` 参数传入
4. **使用新工具**：连接成功后，下一轮思考时即可看到并使用新工具。
技术原理
运行时工具注入：
- 利用 ADK 的依赖注入机制，
get_tools(agent, ...) 获取当前 agent 实例
- 通过
agent.tools.append(new_toolset) 直接修改运行中的工具列表
- ADK 在下一次生成 Prompt 时会自动读取更新后的
agent.tools，将新工具 Schema 发送给 LLM
McpToolset 自动发现：
McpToolset 对象被添加到工具列表后，ADK 会自动调用其内部的工具发现机制- 远程模式：发送
tools/list JSON-RPC 请求获取工具定义
- 本地模式：通过 Stdio 管道与子进程通信，握手后获取工具列表
资源目录说明
此 Skill 不包含额外的 scripts/references/assets 资源，因为：
- 核心逻辑已完全封装在
tools.py 中
- 不需要外部脚本或模板文件
- 所有必要的安全规则和逻辑都在代码内部实现
如果未来需要扩展，可以添加：
references/mcp_registry.json：预定义的常用 MCP 服务列表scripts/validate_mcp.py：MCP 服务健康检查脚本
