在不跨越权限的前提下缓存 MCP 响应

可缓存产品面

只有协议定义的 Read Operation 可缓存：Discovery、Tool、Prompt、Resource 与 Resource Template List，以及 Resource Read。Tool Call、Sampling、Task、Elicitation 与所有 Effectful Operation 永远不缓存。

Cache 位于 Transport 上方，因此 In-process、stdio 与 Streamable HTTP 共享语义。默认 TTL 为零且 Scope 为 Private，直到 Server 主动选择前都保持不缓存行为。

Cache Key

每个 Key 包含 Host 选择的可信 Endpoint Namespace、精确 MCP Method、包含 Pagination Cursor 的序列化参数，以及 Public Scope 或 Private Scope 加 Authorization Partition。

Server 自报 Identity 不是 Namespace。只有相同认证 Authority 才能复用 Private Partition。 Public Sharing 必须由应用显式决定，并共享 Store 与 Endpoint Namespace。

模式与 TTL

Use 返回 Fresh Hit，否则 Fetch 并 Store；Refresh 跳过 Lookup 但更新存储；Bypass 不执行两者。Client Policy 限制所有 Server TTL；Malformed、Future-dated、Missing、Zero 或 Expired Metadata 都是 Miss。

TTL Expiry 是 Lazy 的，不能创建后台 Polling、隐藏网络工作或 Retry Loop。

失效

List-change Notification 使该操作所有缓存页失效；Resource-updated 使精确 Read URI 失效。 被拒绝的 Pagination Request 会使操作页面失效，避免组合不同 List Generation 的 Snapshot。

在把 Notification 交给应用 Subscriber 前先执行 Invalidation。

安全不变量

• Cache Key 包含所有 Request Parameter 与 Cursor；
• Private Entry 永不跨 Authorization Partition；
• Server TTL 不能超过 Client Cap；
• 无效 Metadata 关闭式视为 Miss；
• Effectful Result 永不进入 Cache；
• Cached Content 仍是不可信数据；
• Logout、Credential Rotation 与 Tenant Switch 轮换或清理 Private Partition；
• Cache 可观测性排除敏感 Key Material 与返回内容。

配置安全的客户端缓存

命名空间必须来自可信的服务端地址，私有分区必须来自授权上下文。退出登录、 轮换凭据或切换租户时，都要更换分区。

use runifold_mcp::{Implementation, InMemoryResponseCache, McpClientConfig};
use std::{sync::Arc, time::Duration};
 
let config = McpClientConfig::new(Implementation::new("acme-host", "1.0.0"))
    .with_response_cache(Arc::new(InMemoryResponseCache::new(256)))
    .with_cache_namespace("https://mcp.example.com/v1")
    .with_private_cache_partition(format!("tenant:{tenant_id}:subject:{subject_id}"))
    .with_max_cache_ttl(Duration::from_secs(60));

运维人员要求立即刷新发现结果时使用 CacheMode::Refresh，排查缓存问题时 使用 CacheMode::Bypass。不要用显示名称或服务端返回的元数据生成分区。 如果错误主体命中缓存，应按安全事件处理：轮换分区、清理受影响的 Store， 并审计哪些只读操作使用过该分区。