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-pythonGoogle 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用LlmAgentMcpToolset在 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-flashinstruction系统指令限定智能体作为工作区助手用工具读取、搜索、评论或创建 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(commandnpx, args[...], env{...})且代码版将 token 从环境变量NOTION_API_KEY读取后用json.dumps拼装请求头与 YAML 中静态写入的效果完全一致。操作步骤完整继承自示例 README1. 创建 Notion 集成进入 Notion 官方集成管理页Notion Integrations位于你的 Notion 账户设置中点击 New integration为集成命名并选择所属 workspace复制 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. 授予集成访问权限创建集成后必须显式授权否则所有访问都会失败在 Notion 集成管理页切换到Access选项卡点击 Edit access按需添加需要访问的页面pages与数据库databases。4. 开启 stdio MCP 服务器白名单这是本示例最容易卡住的一步。YAML 声明了 stdio MCP 服务器意味着加载配置的那一刻就会在本地执行npx子进程。ADK 默认拒绝这种行为——否则任何来源的 agent 配置文件都能借智能体启动之机执行任意命令。因此运行前必须先设置export ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS1只有当你信任该进程将加载的全部 agent 配置时才应设置此变量。5. 运行智能体adk run在示例目录下执行即可与你的 Notion workspace 交互式对话。安全开关的源码级实现README 中ADK 默认拒绝 stdio这句话对应到源码校验发生在McpToolset.from_config()类方法中mcp_toolset.py#L628-L673。其逻辑可以归纳为三层开关判定常量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 的应用在启动时以编程方式放行替代设置环境变量拒绝分支当配置中stdio_server_params或stdio_connection_params任一存在而开关未开启时from_config抛出ValueError错误信息明确给出三条出路——改用 Python 代码构造McpToolset、改用远程传输sse_connection_params或streamable_http_connection_params、或在只加载可信配置时设置ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS1连接参数选取开关通过后按stdio_server_params扁平旧写法→stdio_connection_params嵌套写法即本示例所用→sse_connection_params→streamable_http_connection_params的优先级解析出唯一的连接参数全部缺失则报错 No connection params found。从源码结构看这条校验只作用于配置加载路径from_configPython 代码里直接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——列举数据库。常见问题现象原因与处理Unauthorized 错误检查OPENAPI_MCP_HEADERS中的 Bearer token 是否正确、是否被 shell 引号截断Object not found 错误集成未获得该页面/数据库的访问权回到第 3 步补充授权请求头版本不匹配Notion-Version示例为2022-06-28需与 MCP 服务器期望的 Notion API 版本一致启动即报 stdio 相关ValueError未执行export ADK_ALLOW_CONFIG_STDIO_MCP_SERVERS1或配置被不受信任的路径加载按上文安全开关一节选择放行方式或改用代码/远程传输小结该示例展示了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考