valkryhx/google_adk_agent / skills/dynamic-mcp
Dynamic MCP Loader
Verified动态 MCP 工具加载器,支持运行时连接远程 HTTP/SSE MCP 服务或启动本地 MCP 进程,让 Agent 根据需求即时扩展能力。适用于用户提到不熟悉的 MCP 服务时,通过搜索发现连接方式后动态加载。
SKILL.md
View on GitHub---
name: "Dynamic MCP Loader"
description: "动态 MCP 工具加载器,支持运行时连接远程 HTTP/SSE MCP 服务或启动本地 MCP 进程,让 Agent 根据需求即时扩展能力。适用于用户提到不熟悉的 MCP 服务时,通过搜索发现连接方式后动态加载。"
---
# Dynamic MCP Loader
## 概述
Dynamic MCP Loader 是一个**元工具**(Meta-Tool),赋予 Agent **"自主扩张能力"**。
它允许 Agent 在运行时动态加载新的 MCP 工具,而无需重启服务或修改配置文件。Agent 可以:
1. 通过 Web 搜索发现 MCP 服务的连接方式(URL 或 npx 命令)
2. 调用 `connect_mcp` 工具动态挂载该服务
3. 立即使用新加载的 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) 方式提供。
**执行步骤**:
1. 通过搜索获取 MCP 服务的 URL
2. 调用 `connect_mcp`,`mode="remote"`,`source` 填写 URL
3. 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` 等命令在本地启动。
**执行步骤**:
1. 通过搜索获取启动命令(如 `npx -y @modelcontextprotocol/server-git`)
2. 将命令拆解为 `command` 和 `args` 列表
3. 调用 `connect_mcp`,`mode="local"`
4. 如果需要 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`
**拆解为**:
```python
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
**示例**:
```python
env_vars={
"BRAVE_API_KEY": "用户提供的Key",
"DEBUG": "true" # 如果需要调试模式
}
```
## 安全机制
### 1. 命令白名单
**本地模式仅允许以下基础命令**:
- `npx`, `uvx`: Node.js 包管理工具
- `node`: Node.js 运行时
- `python`, `python3`: Python 解释器
**拒绝示例**:
```python
connect_mcp(mode="local", source="rm", args=["-rf", "/"])
# 返回: "[Security] 拒绝执行:命令 'rm' 不在白名单中"
```
### 2. 参数注入防护
**禁止参数中包含以下字符**:
- 管道符 `|`
- 重定向 `>`, `<`
- 命令分隔 `;`, `&`
- 命令替换 `` ` ``, `$(`
**拒绝示例**:
```python
connect_mcp(mode="local", source="npx", args=["-y", "package; rm -rf /"])
# 返回: "[Security] 参数 'package; rm -rf /' 含非法字符"
```
### 3. 智能去重
**防止重复加载同一服务**:
- 远程模式:对比 URL(忽略末尾斜杠)
- 本地模式:对比 `command + args` 完全匹配
**示例**:
```python
# 第一次调用
connect_mcp(mode="remote", source="https://mcp.context7.com/mcp")
# 返回: "[Success] ..."
# 第二次调用相同 URL
connect_mcp(mode="remote", source="https://mcp.context7.com/mcp/")
# 返回: "无需重复连接:已连接到远程服务 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 中添加**:
```markdown
### 动态 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 服务健康检查脚本
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |