Summary
Propose adding ETag + conditional-request support (If-None-Match → 304 Not Modified) as a SHOULD in docs/discovery.md for endpoints serving a Server Card (and the MCP Catalog).
Current state
docs/discovery.md specifies caching only via Cache-Control:
Cache-Control: public, max-age=3600
MCP Clients SHOULD respect Cache-Control headers and avoid unnecessary polling.
There is no guidance on ETag / conditional requests. The Server Card and Catalog are effectively static documents, so they are a natural fit for entity-tag validation.
Proposal
Add a SHOULD-level recommendation, roughly:
- Servers serving a Server Card / Catalog SHOULD emit a strong
ETag derived from the served representation (e.g. a hash of the canonical response body).
- Servers SHOULD honor
If-None-Match and return 304 Not Modified (with the ETag and Cache-Control headers, empty body) when the validator matches; * matches any current representation.
- Clients SHOULD send
If-None-Match when revalidating a previously fetched card/catalog (e.g. after max-age lapses).
This complements Cache-Control: max-age rather than replacing it: max-age avoids requests within the freshness window; ETag/304 makes the post-expiry revalidation cheap (no re-download of an unchanged document).
Rationale
- Standard HTTP caching semantics (RFC 9110); broadly supported by clients/CDNs/proxies.
- Cuts bandwidth for frequently-revalidated, rarely-changed documents.
- For multi-tenant deployments where the card body varies by host/environment, an ETag computed from the exact served bytes naturally yields a per-representation validator.
Reference implementations
Neither current reference implementation emits an ETag today (both set Content-Type, CORS, and Cache-Control: public, max-age=3600 only):
We're adding ETag support to these (and to a production GitHub deployment of the Server Card). Standardizing the behavior in discovery.md — even as a SHOULD — would keep implementations from diverging on the validator format and If-None-Match handling.
Questions for the WG
- SHOULD vs MAY for the server side (emit
ETag + honor If-None-Match)?
- Any preference on validator form (strong vs weak; recommended hash) so implementations interoperate, or leave it opaque per RFC 9110?
- Should the same guidance apply uniformly to both the Server Card and the Catalog endpoints?
Happy to open a PR against docs/discovery.md once there's directional agreement.
Summary
Propose adding ETag + conditional-request support (
If-None-Match→304 Not Modified) as a SHOULD indocs/discovery.mdfor endpoints serving a Server Card (and the MCP Catalog).Current state
docs/discovery.mdspecifies caching only viaCache-Control:There is no guidance on
ETag/ conditional requests. The Server Card and Catalog are effectively static documents, so they are a natural fit for entity-tag validation.Proposal
Add a SHOULD-level recommendation, roughly:
ETagderived from the served representation (e.g. a hash of the canonical response body).If-None-Matchand return304 Not Modified(with theETagandCache-Controlheaders, empty body) when the validator matches;*matches any current representation.If-None-Matchwhen revalidating a previously fetched card/catalog (e.g. aftermax-agelapses).This complements
Cache-Control: max-agerather than replacing it:max-ageavoids requests within the freshness window;ETag/304makes the post-expiry revalidation cheap (no re-download of an unchanged document).Rationale
Reference implementations
Neither current reference implementation emits an
ETagtoday (both setContent-Type, CORS, andCache-Control: public, max-age=3600only):We're adding ETag support to these (and to a production GitHub deployment of the Server Card). Standardizing the behavior in
discovery.md— even as a SHOULD — would keep implementations from diverging on the validator format andIf-None-Matchhandling.Questions for the WG
ETag+ honorIf-None-Match)?Happy to open a PR against
docs/discovery.mdonce there's directional agreement.