MCP 配置指纹与隔离
判断哪些变化创建新连接,哪些过滤仍可共享 transport。
同名 MCP 服务可以有多个 pool entry,因为认证、环境或共享工具快照配置不同。fingerprint 的目标是只在有效连接配置一致时复用,而不是仅按名称复用。
参与键的字段
当前实现覆盖 transport、command、args、cwd、env、url、httpUrl、tcp、headers、timeout、自动版本协商、OAuth、App resource 大小与期限,以及 authProviderType、targetAudience、targetServiceAccount。
env 和 headers 按键排序。App resource 限制先采用与执行处相同的默认、取整和 clamp 规则,再进入 hash,因此有效策略相同的原始值可以共享。
这些 App 限制虽然不是连接地址,也必须进入键:discovery 将它们保存进共享工具 snapshot,不会在每个 session 再投影。新增类似生命周期的字段时,应同时评估共享键。
OAuth 规范化
未配置、null、空对象或 enabled:false 都作为未启用 OAuth。启用时键包括 clientId、clientSecret、scopes、audiences、authorizationUrl、tokenUrl、redirectUri、tokenParamName、registrationUrl。
scopes 与 audiences 排序;缺失字段规范为 null。只改变 secret、audience 或 redirectUri 也会得到不同有效指纹,不能因名称相同就共用原凭据连接。
不参与键的字段
includeTools、excludeTools、trust、alwaysLoadTools、description、extensionName 和 discoveryTimeoutMs 不直接改变 transport 键。过滤由 session view 负责:excludeTools 精确匹配,includeTools 可去掉首个 (...) 参数后缀再匹配工具名。
discoveryTimeoutMs 不在键中意味着同键并发 acquire 使用先到配置的 discovery timeout。不同会话写了不同值,不保证分别得到各自期限。
不参与键不表示字段无效,只表示它的作用域或生命周期不同。特别是 trust 不能靠共享键提供权限证明。
标识与状态展示
内部 connection ID 用服务名、分隔符和指纹组成。服务名本身可包含 ::,解析必须使用 parseConnectionId 的最后一个分隔位置,不能用 startsWith 判断同名 sibling。
外部快照暴露 entryCount 和 entrySummary,后者只含 entryIndex、refs、status;不暴露原始 OAuth/env 指纹。两项一起出现,mcp_workspace_pool 表示这类 pool-aware 形状。
disabledReason 可区分 config 禁用和 budget 拒绝。一个名称的聚合状态为 connected,不代表该名称下每个 entry 都健康;需要按 entrySummary 排查。
PoolEntry 的原始 cfg 保持私有;只需传输类型时使用 transportKind,而不要把 header、env 或 OAuth 配置透传到状态界面。