adk-python：用 YAML 配置驱动 Notion 智能体——McpToolset 接入 Notion MCP Server 与 Stdio 安全开关

adk-python：用 YAML 配置驱动 Notion 智能体——McpToolset 接入 Notion MCP Server 与 Stdio 安全开关

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

本篇以 adk-python（Google Agent Development Kit 的 Python 实现）中"基于配置的 MCP 工具示例"为主体，讲解如何仅凭一份root_agent.yaml就把一个能读写 Notion 页面与数据库的智能体跑起来：涵盖 Notion 集成的创建与授权、McpToolset的 stdio 连接参数写法、ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS安全开关的底层校验逻辑，以及常见问题排查。读完后你能掌握配置式智能体的完整落地流程，并理解 ADK 为什么默认禁止在配置文件中声明 stdio MCP 服务器。

示例定位：配置式与代码式两条路径

仓库中同一个 Notion 智能体存在两种等价实现，本示例属于其中"配置驱动"的一条：

• 配置式（本文主体）：root_agent.yaml，通过adk run直接加载 YAML 配置启动智能体，无需编写 Python 代码；
• 代码式（对照参考）：agent.py，用LlmAgent+McpToolset在 Python 中构造完全相同的智能体。

配置式示例的完整操作说明见 README，其内容（含所有配置步骤）被完整继承并在下文逐项展开。

核心配置解析：root_agent.yaml 全字段

整个智能体由一份 YAML 文件定义，逐字段说明如下：

name: notion_agent model: gemini-2.5-flash instruction: | You are my workspace assistant. Use the provided tools to read, search, comment on, or create Notion pages. Ask clarifying questions when unsure. tools: - name: McpToolset args: stdio_connection_params: server_params: command: "npx" args: - "-y" - "@notionhq/notion-mcp-server" env: OPENAPI_MCP_HEADERS: '{"Authorization": "Bearer <your_notion_token>", "Notion-Version": "2022-06-28"}'

• name/model：智能体名称与底层模型，此处使用gemini-2.5-flash；
• instruction：系统指令，限定智能体作为"工作区助手"，用工具读取、搜索、评论或创建 Notion 页面，并在不确定时反问澄清；
• tools：声明式地实例化McpToolset工具集，name: McpToolset指定类名，args即该类构造参数；
• stdio_connection_params.server_params：描述 stdio 传输的具体服务器进程——command: npx、args: ["-y", "@notionhq/notion-mcp-server"]表示加载配置时由npx拉起官方 Notion MCP 服务器包；
• env.OPENAPI_MCP_HEADERS：以 JSON 字符串形式注入 HTTP 请求头，Authorization: Bearer <token>携带 Notion 集成密钥，Notion-Version: 2022-06-28指定 Notion API 版本。Notion MCP 服务器通过该环境变量把请求头透传给 Notion REST API。

对照代码式实现 agent.py 可以验证参数映射关系：YAML 中的stdio_connection_params对应StdioConnectionParams，其内层server_params对应StdioServerParameters(command="npx", args=[...], env={...})，且代码版将 token 从环境变量NOTION_API_KEY读取后用json.dumps拼装请求头，与 YAML 中静态写入的效果完全一致。

操作步骤（完整继承自示例 README）

1. 创建 Notion 集成

1. 进入 Notion 官方集成管理页（Notion Integrations，位于你的 Notion 账户设置中）；
2. 点击 "New integration"；
3. 为集成命名并选择所属 workspace；
4. 复制 "Internal Integration Secret"（以ntn_开头）。

Notion MCP 服务器（npm 包@notionhq/notion-mcp-server）的详细说明可查阅其官方 npm 页面。

2. 配置智能体

将 root_agent.yaml 中的<your_notion_token>替换为真实 token。README 给出的环境变量写法为：

env: OPENAPI_MCP_HEADERS: '{"Authorization": "Bearer secret_your_actual_token_here", "Notion-Version": "2022-06-28"}'

注意 JSON 是单行字符串内嵌在 YAML 中，引号需保持成对。

3. 授予集成访问权限

创建集成后必须显式授权，否则所有访问都会失败：

1. 在 Notion 集成管理页切换到Access选项卡；
2. 点击 "Edit access"；
3. 按需添加需要访问的页面（pages）与数据库（databases）。

4. 开启 stdio MCP 服务器白名单

这是本示例最容易卡住的一步。YAML 声明了 stdio MCP 服务器，意味着加载配置的那一刻就会在本地执行npx子进程。ADK 默认拒绝这种行为——否则任何来源的 agent 配置文件都能借智能体启动之机执行任意命令。因此运行前必须先设置：

export ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS=1

只有当你信任该进程将加载的全部 agent 配置时才应设置此变量。

5. 运行智能体

adk run

在示例目录下执行即可与你的 Notion workspace 交互式对话。

安全开关的源码级实现

README 中"ADK 默认拒绝 stdio"这句话对应到源码，校验发生在McpToolset.from_config()类方法中（mcp_toolset.py#L628-L673）。其逻辑可以归纳为三层：

1. 开关判定：常量ALLOW_CONFIG_STDIO_SERVERS_ENV_VAR = "ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS"定义于 mcp_toolset.py#L71。_allow_config_stdio_servers_enabled()（L92-L96）先看进程内覆盖值_allow_config_stdio_servers，为None时再回落到环境变量判断。仓库同时提供_set_allow_config_stdio_servers()（L78-L89）供内嵌 ADK 的应用在启动时以编程方式放行，替代设置环境变量；
2. 拒绝分支：当配置中stdio_server_params或stdio_connection_params任一存在而开关未开启时，from_config抛出ValueError，错误信息明确给出三条出路——改用 Python 代码构造McpToolset、改用远程传输（sse_connection_params或streamable_http_connection_params）、或在只加载可信配置时设置ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS=1；
3. 连接参数选取：开关通过后，按stdio_server_params（扁平旧写法）→stdio_connection_params（嵌套写法，即本示例所用）→sse_connection_params→streamable_http_connection_params的优先级解析出唯一的连接参数，全部缺失则报错 "No connection params found"。

从源码结构看，这条校验只作用于"配置加载"路径（from_config），Python 代码里直接McpToolset(connection_params=...)构造不受该开关限制——这正是错误信息建议"构造于代码"的原因：代码由你本人编写、受版本控制，而配置文件可能来自他人。

交互示例与排错

示例查询

README 给出的四类典型交互，可直接作为验收用例：

• "What can you do for me?"——探测智能体已加载的 MCP 工具；
• "Search for 'project' in my pages"——页面检索；
• "Create a new page called 'Meeting Notes'"——创建页面；
• "List all my databases"——列举数据库。

常见问题

小结

该示例展示了 adk-python "code-first 之外"的另一面：一份root_agent.yaml即可完成模型、指令、MCP 工具集与鉴权头的全量声明，配合adk run即可运行。理解其关键在于两点——YAML 中stdio_connection_params与 Python 构造参数的等价映射，以及McpToolset.from_config中针对配置来源不可信而设置的 stdio 门禁。若你的场景中 agent 配置完全受控（如企业内部部署），可设置环境变量或以_set_allow_config_stdio_servers(True)放行；反之，优先考虑sse_connection_params/streamable_http_connection_params远程传输，或在 Python 代码中显式构造McpToolset。

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python