---
title: "MCPP Caching"
description: "复用远程 MCP 的工具与资源发现结果，减少重复列表请求；本文说明缓存如何接入连接生命周期，以及何时必须回源。"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# MCPP Caching

[MCPP Caching](https://github.com/KonghaYao/peri-studio/blob/main/MCPP.md) 在 Peri 架构中的位置是 MCP 连接后的发现结果缓存层。它不缓存工具执行结果，也不替代连接握手；它处理的是 `tools/list`、资源列表和部分资源读取返回的描述或内容，目标是避免每次启动重复下载未变化的数据。

这层缓存位于 `McpClientPool` 的连接与工具 bridge 之间。连接仍然要建立，server 仍然要完成协议协商，但列表请求可以根据 server 的缓存声明、本地快照和连接配置决定是否回源。

## 它解决什么问题

远程 MCP 启动时，工具定义和资源清单通常需要额外的网络请求。工具数量越多，列表响应的传输、解析和 bridge 构造越占启动阶段的时间；这些工作与本次任务是否真的使用某个工具无关。

MCPP Caching 复用的是发现结果，不是执行结果。命中缓存时，Peri 在握手完成后读取本地快照，避免再次请求完整列表；连接、权限检查和实际工具调用仍按正常路径执行。

## 如何判断缓存仍然有效

对于工具列表，server 通过 `io.mcpp/server-cache-version` 声明缓存版本。Peri 把这个版本与本地快照比较，版本一致且当前连接配置允许持久化时才复用；版本缺失、版本变化、快照损坏或写入失败时回源取得新列表。

资源列表和资源读取使用另外的缓存元数据。响应可以提供缓存范围和有效期，Peri 再结合 `Public`/`Private` scope、TTL 以及当前连接是否包含静态 header、URL query、stdio env 或 OAuth 凭据，决定是否允许跨进程保存。

## 变化如何使缓存失效

工具列表变化通知会使工具列表缓存失效，资源列表变化通知会使资源列表缓存失效。这里的失效首先针对缓存记录，不代表已经装配到 Agent 的工具 bridge 会立即重建。

下一次需要对应列表时，Peri 再判断是否命中有效快照，或向 server 发起请求。资源更新通知还会使对应资源缓存失效；它不会自动读取所有资源，也不会替换当前 session 已经持有的全部资源内容。

## 基于 MCP 做了什么处理

MCP 本身规定 server 可以返回工具和资源列表，但不规定宿主如何跨进程复用这些结果。MCPP 增加了缓存版本、scope 和 TTL 等声明，让 server 能对“这份列表可以复用多久、在什么范围复用”提供机器可读的信息。

Peri 在此基础上增加本地缓存目录、版本匹配、凭据安全判断和失效处理。缓存键不能只使用 server 名称，还要结合连接配置和 server 声明，避免把一个连接的工具表误用于另一个连接。

## 实际收益与限制

满足版本和持久化准入条件时，后续连接可以跳过未变化的列表请求，启动阶段少一次或多次远程数据传输。收益取决于网络延迟、列表大小、server 初始化时间和缓存命中率，不能从缓存机制本身推出固定的启动耗时。

首次连接、版本升级、缓存失效、凭据策略禁止持久化和缓存损坏时仍然回源。排查启动时间时，应把连接握手、列表请求和缓存命中分开观察。

Source: https://konghayao.github.io/peri-cool/posts/engineering/mcpp-caching/index.mdx