IronClaw 的 Notion 托管 MCP 扩展[mcp]运行时形态与 OAuth 凭据注入的完整解析【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw导读notion-mcp是 IronClaw 中以数据驱动方式实现的 Notion 工作区集成包它不静态声明任何工具而是通过 Notion 官方托管 MCP 服务器https://mcp.notion.com/mcp在运行时动态发现工具是仓库中托管 MCPhosted-MCP形态的标准范例。本文将以 crates/extensions/packages/notion-mcp/README.md 为骨架结合其 manifest.toml、18 组 prompt/schema 资产以及ironclaw_extension_host的托管 MCP 发现机制讲清[mcp]与[runtime] [[tools]]两种形态的差异、OAuth 2.1 动态注册客户端的凭据配置要点以及数据包如何嵌入、发现并发布为普通工具面。读完后你将能独立理解并配置任一托管 MCP 类的 IronClaw 扩展包。一、包定位托管 MCP 形态的标准答案notion-mcp的扩展 id 为notion是一个纯数据包data-only package——即没有自己的 crate、不编译 WASM、不实现 channel adapter目录内只有manifest.toml、prompts/与schemas/三类资产。它的特殊之处在于它是仓库中hosted-MCP 形态[mcp]的范本Surfaces[mcp]托管服务器无静态[[tools]][auth.notion]OAuth 授权面Vendor凭据权威方notionRuntimeMCP 加载器工具发现discovery由ironclaw_extension_host拥有Contentsmanifest.toml、prompts/、schemas/由ironclaw_extension_support::packages::notion嵌入Tests清单投影由cargo test -p ironclaw_extension_registry覆盖宿主侧发现/注册由cargo test -p ironclaw_extension_host覆盖。关于包家族的整体规则目录自包含、包与 crate 的取舍、资产边界等详见 crates/extensions/AGENTS.md。用一句话概括其设计意图工具来自 Notion 的托管 MCP 服务器而不是静态声明——激活之后一个被发现的工具就是一个普通工具面与静态声明的工具在使用上无异。二、清单形态[mcp]与[runtime] [[tools]]的本质区别传统数据包如github、google-docs在清单中通过[runtime]声明执行环境、通过[[tools]]静态列出每个工具。而notion-mcp用一段[mcp]块取而代之把服务器地址 命名空间 工具数量上限 凭据交给宿主由宿主负责连接、发现并注册工具。完整清单如下manifest.tomlschema_version reborn.extension_manifest.v3 id notion name Notion version 0.1.0 description Notion MCP tools for creating, searching, fetching, querying, and managing Notion workspace content. trust third_party [mcp] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } server https://mcp.notion.com/mcp namespace notion max_tools 256 default_permission ask effects [network, use_secret, external_write] [[mcp.credentials]] handle mcp_notion_access_token vendor notion scopes [] injection { type header, name authorization, prefix Bearer } [auth.notion] method oauth2_code display_name Notion account authorization_endpoint https://mcp.notion.com/authorize token_endpoint https://mcp.notion.com/token scopes [] [auth.notion.refresh] rotates_refresh_token true [auth.notion.token_response] access_token /access_token refresh_token /refresh_token expires_in /expires_in scope { path /scope, missing fallback_to_requested }2.1[mcp]核心字段逐项解读字段值含义serverhttps://mcp.notion.com/mcp托管 MCP 服务器端点宿主在发现阶段据此发起连接namespacenotion发现到的工具归入的命名空间与扩展 id 一致max_tools256单次发现允许注册的工具数量上限宿主将其作为发现产出的硬性封顶default_permissionask工具默认权限模式未获得显式授权前调用需要询问effectsnetwork、use_secret、external_write该扩展声明的能力副作用网络访问、使用机密、外部写入origin_gate_matrixloop_run gated_unless_granted、product forbidden、automation forbidden按调用来源循环运行 / 产品 / 自动化设置的准入门控仅在主循环中且获得授权时放行产品与自动化来源一律禁止2.2max_tools在宿主侧如何被强制执行max_tools并非装饰性配置。从 hosted_mcp_discovery_authority.rs 的源码结构可以看到宿主为每次发现生成一个McpDiscoveryFence权威围栏其字段正是package、manifest_hash、max_tools、credential_accounts四者发现过程在生命周期操作锁之外运行只有围栏的投影相等性校验通过该代发现结果才被允许发布进活动快照still_authorizes。这意味着max_tools、清单摘要、凭据账户中的任一项发生变化都会使旧的发现代失效并触发重检从而保证目录发现不会把过期清单或过期凭据的产物带入活动状态。三、凭据面OAuth 2.1 动态注册公共客户端Notion 托管 MCP 采用 OAuth 2.1且使用动态客户端注册RFC 7591——清单中刻意不写client_credentials块正是为了声明这一点。同时 Notion 的 access token 约一小时后过期、refresh token 单次使用即轮换因此清单通过三段配置精确刻画了这一行为[[mcp.credentials]]注入方式handle mcp_notion_access_token定义了凭据句柄injection { type header, name authorization, prefix Bearer }说明宿主在发送 MCP 请求时将该凭据以Authorization: Bearer token请求头的形式注入——这是宿主在**受介导的出站mediated egress**上替扩展完成凭据注入的典型机制。[auth.notion]授权流程method oauth2_code走标准授权码流程authorization_endpoint与token_endpoint分别指向https://mcp.notion.com/authorize与https://mcp.notion.com/tokendisplay_name Notion account用于用户在授权界面中识别账户。[auth.notion.refresh]与[auth.notion.token_response]rotates_refresh_token true声明刷新令牌轮换token_response给出了从令牌端点 JSON 响应中提取access_token、refresh_token、expires_in、scope的 JSONPath/access_token、/refresh_token、/expires_in、/scope其中scope在缺失时回退为请求时的 scopemissing fallback_to_requested。清单注释特意强调如果不配置 refresh/expiry 捕获引擎会把令牌当作永不过期存储所有 Notion 连接将在一小时内失效。这三段配置是 Notion 集成可用性的生命线也是任何短命 token 单次轮换类托管 MCP 供应商接入时的必抄作业。四、工具面18 个发现工具与其 prompt/schema 资产虽然工具在运行时才发现但包内为每个工具预置了模型可见的 prompt 文档与JSON Schema 输入/输出定义additionalProperties: true的宽松透传模式参数直接透传给 Notion MCP。清单按命名空间notion组织完整清单如下工具promptprompts/notion/schemaschemas/notion/用途notion-searchnotion-search.mdnotion-search.input/output.v1.json搜索工作区内容与已连接数据源notion-fetchnotion-fetch.mdnotion-fetch.input/output.v1.json获取指定 page/database/data source 的完整内容notion-create-pagesnotion-create-pages.md同名 input/output创建一页或多页notion-update-pagenotion-update-page.md同名 input/output更新已有页面notion-move-pagesnotion-move-pages.md同名 input/output移动页面notion-duplicate-pagenotion-duplicate-page.md同名 input/output复制页面notion-create-databasenotion-create-database.md同名 input/output创建数据库notion-update-data-sourcenotion-update-data-source.md同名 input/output更新数据源notion-create-viewnotion-create-view.md同名 input/output创建视图notion-update-viewnotion-update-view.md同名 input/output更新视图notion-query-data-sourcesnotion-query-data-sources.md同名 input/output查询数据源notion-query-database-viewnotion-query-database-view.md同名 input/output按视图语义查询数据库过滤/排序由视图控制notion-create-commentnotion-create-comment.md同名 input/output创建评论notion-get-commentsnotion-get-comments.md同名 input/output获取评论notion-get-teamsnotion-get-teams.md同名 input/output获取团队信息notion-get-users / notion-get-user同名 md同名 input/output获取用户列表 / 单个用户notion-get-selfnotion-get-self.md同名 input/output获取当前授权账户自身信息prompt 文案清晰地表达了使用约束与路由意图例如notion-search.md提供简洁的query仅在需要时透传 Notion MCP 支持的额外参数notion-fetch.md在 Notion 搜索之后、用户需要某个 page/database/data source 的完整内容时使用提供id或urlnotion-query-database-view.md当特定视图应当控制过滤或排序时优先使用notion-create-pages.md/notion-update-page.md除非已获得批准否则在创建/修改工作区内容前先询问——这与default_permission ask及origin_gate_matrix的准入语义互为呼应。以notion-search.input.v1.json为例输入 schema 仅要求一个非空字符串queryminLength: 1其余参数由additionalProperties: true开放透传这是发现式工具的通用形态本地只做最小约束完整参数面由远端 MCP 目录在激活后给出。五、数据包如何嵌入extension_support::packages::notion作为纯数据包notion-mcp没有独立 crate其资产在编译期被ironclaw_extension_support的包模块嵌入。核心实现位于 crates/extensions/ironclaw_extension_support/src/packages/notion.rsID notiondisplay_name Notion MCPmanifest_toml通过include_str!(../../../packages/notion-mcp/manifest.toml)嵌入assets()通过宏批量include_bytes!嵌入全部 schema 与 prompt 资产目录映射为schemas/notion/*与prompts/notion/*提供PackageOnboarding引导文案安装后提示Notion 需要 OAuth 授权后 MCP 工具才能运行授权完成后 IronClaw 自动完成安装并发布 MCP 工具trust_effects显式声明DispatchCapability、Network、UseSecret、ExternalWrite四项信任效果——注释强调该信任授予是宿主侧的独立断言纵深防御与清单声明相互印证而非派生关系。该模块被登记进 crates/extensions/ironclaw_extension_support/src/packages/mod.rs 的PACKAGES清单(notion::ID, notion::bundle)bundled_packages()以不透明PackageBundle的形式交付给 composition 与 CLI 消费而 generic 代码只接触 id 与 bundle从不指名具体包——这与家族规则中供应商名只允许出现在packages/*与extension_support的约束一致。六、宿主侧生命周期发现、授权围栏与发布从源码结构可以还原一条完整的托管 MCP 生命周期链路相关文件均在 crates/extensions/ironclaw_extension_host/src解析与准备hosted_mcp_manifest.rs定义托管 MCP 清单模型hosted_mcp_preparation.rs在激活事务中读取安装记录、解析[mcp]块并取出max_tools等参数发现mcp_discovery.rs负责连接远端服务器并发现工具目录发现运行在生命周期操作锁之外且由hosted_mcp_discovery_authority.rs的McpDiscoveryFence捕获清单摘要 max_tools 凭据账户作为权威输入发布active_publication.rs、mcp_catalog_safety.rs与hosted_mcp_admission.rs共同把关发现结果准入活动快照只有围栏still_authorizes通过才发布注册registration_pipeline_boundary由crates/app/ironclaw_architecture_tests/tests/reborn_registration_pipeline_boundary.rs强制约束托管 MCP 注册词汇只存在于 host/registry 作用域内不泄漏到 generic 代码。此外McpDiscoveryFence还刻意不派生PartialEq避免调用方用完整字段集含凭据行的易变时间戳比较围栏而引发无谓的重检credential_authority投影则剔除created_at/updated_at只比较账户身份、状态、secret 句柄与授权 scope从而在良性写操作不触发重检与真实权限变化失败即关闭之间取得平衡。七、测试与验证README 明确给出了两个验证入口# 清单投影registry 侧验证 manifest 解析与投影正确性 cargo test -p ironclaw_extension_registry # 宿主侧发现/注册验证 hosted-MCP 发现、围栏与发布管线 cargo test -p ironclaw_extension_hosthosted_mcp_discovery_authority.rs与activation_transaction.rs中的max_tools测试样例进一步表明工具数量封顶、发现代失效重检等行为都有对应测试覆盖。家族层级的架构门控如reborn_extension_specificity.rs禁止 generic 代码出现供应商名、reborn_registration_pipeline_boundary.rs隔离注册词汇则统一由cargo test -p ironclaw_architecture_tests执行保证notion这类数据包不会侵蚀宿主权威。八、实操要点小结新增同类托管 MCP 扩展以notion-mcp为模板在crates/extensions/packages/vendor-mcp/下放置manifest.tomlprompts/schemas/在extension_support中新增嵌入模块并登记进PACKAGES清单即可若远端服务器需要从运维 LLM 管理配置中动态补丁如nearai-mcp则还需阅读对应模块头部说明。凭据必配三项[[mcp.credentials]]的 header 注入、[auth.vendor]的授权码端点、以及短命 token 场景下的refreshtoken_response捕获缺失后者会导致令牌被当作永不过期而连接失效。权限与门控max_tools是发现的硬性封顶default_permission与origin_gate_matrix决定调用准入effects声明能力副作用三者共同构成对第三方服务器发现出的工具的宿主侧约束。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考