Tools/list Stamps vs Caching: SEP-2549 Spec Analyzed
An analysis of Dev.to insights on SEP-2549 spec, exploring why TTL and cache stamps on tools/list are reuse claims rather than proof of caching.
Stock photo for illustration only, not from the actual event
- The SEP-2549 spec introduced ttlMs and cacheScope to MCP tools/list, mirroring HTTP Cache-Control.
- Stamps on lists are claims about future reuse, not proof that the next call is actually cacheable.
- The contrast-smoke command in mcp-better ensures that negative test cases remain explicitly named and active.
- Testing requires observations capable of failing, rather than merely verifying the presence of fields.
In the software development ecosystem, data caching mechanisms often spark intense debates regarding their reliability. A recent insightful article published on Dev.to by user wolfejam examines the 2026-07-28 specification (SEP-2549), which added list-cache stamps such as ttlMs and cacheScope to the Model Context Protocol (MCP) tools/list, modeled closely after HTTP Cache-Control.
This specification was built on the notion that clients should know precisely when tools/list data remains fresh. However, the author points out that HTTP taught this lesson long ago: a header like Cache-Control: max-age=60 is merely a statement, not a guarantee that the subsequent GET request will return identical bytes. MCP imported the terminology without importing a rigorous test suite to validate it.
Stock photo for illustration only, not from the actual event
Consequently, a server can output ttlMs: 60000 and cacheScope: Public while dynamically altering its catalog on the very next call. A validation probe checking solely for field presence will still pass successfully, meaning the system effectively ships a silent discrepancy that simple probes fail to catch.
From an architectural standpoint, understanding protocol-level caching semantics is vital to prevent discrepancies between a declared state and the server's actual runtime behavior. A well-formed stamp does not guarantee underlying cache behavior. Developers must implement falsifiable tests rather than blindly trusting the mere existence of metadata keys.
To address this, the project introduced a labeled companion named mcp-worse alongside mcp-better, featuring a contrast-smoke command that passes only if the compliant server meets the catalog contract while the non-compliant server fails it. For instance, mcp-better includes an extra tool called confirm_echo, whereas mcp-worse lists only echo and health, ensuring clear divergence.
A typical test output run captures the following state:
- better names: ["health", "echo", "confirm_echo"], ttl: Some(60000), scope: Some(Public)
- worse names: ["echo", "health"], ttl: None, scope: None
- contrast-smoke: OK (better contract · worse unstamped · worse names≠health,echo,confirm_echo)
Ultimately, the core takeaway is that ttlMs and cacheScope stamps on tools/list represent reuse claims rather than concrete proof of caching behavior. Confirming field presence only proves that the server made a statement, not that a client is justified in skipping subsequent calls.
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment