The Distribution Lifecycle: Pins, Caches, and Updates

For Agent Skills, knowing that a payload is identifiable is not the same as knowing which payload a user will receive today. This chapter follows the repository's distribution lifecycle: how MCP resolves a catalog version and keeps registry knowledge warm, how the CLI maintains a longer-lived cache and installed state, and how content hashes turn “update” from a clock-based guess into a comparison of actual skill identity. The practical result is a way to reason about freshness without treating availability as proof of currency.

MCP treats registry knowledge as a time-bounded view

The MCP server does not construct skill URLs from a permanently mutable @latest reference after it starts. It first resolves a catalog reference. An environment-provided SKILLS_CDN_REF can pin the value for a deployment or test; otherwise the server queries npm for the latest published catalog version and retains the resolved result for the process. It then builds versioned jsDelivr URLs for the registry and skill files.

That resolution step matters because a catalog version is a boundary around the content the server intends to use. If the server looked up a moving alias separately for the registry and each file, a single conversation could observe different catalog revisions. Resolving once does not independently authenticate the package or make it permanent, but it makes the session's URL construction coherent. The server can say which published reference it is addressing before it asks for the registry or a skill file.

After the first successful registry fetch, MCP keeps the parsed registry in memory for 15 minutes. Within that period, a request can use the cached data without another network call. Once the time-to-live expires, the server attempts conditional revalidation with an ETag when one is available. A 304 Not Modified renews the cache age without downloading the registry again; a fresh 200 response replaces the data and its ETag. This separates “the cache is old enough to check” from “the registry content actually changed.”

The failure behavior distinguishes a cold start from a warm service. At cold start, the server retries the registry request and refuses to start if it cannot load a valid registry. There is no known catalog from which it could build a trustworthy search index. After warm-up, a failed refresh can return the stale in-memory registry instead, with the failure logged to standard error. Availability wins over freshness, but the stale fallback does not become a current publication merely because it remains usable.

The server also refreshes the registry in the background and rebuilds its search indexes when new data arrives. That means a long-running MCP process can move from one registry view to another without requiring a restart. The transition is useful for a catalog that changes, but it also means that the exact search results available later in a session may reflect a newer registry than the one that produced an earlier candidate.