spec: decouple Mcp-Param-* header emission from schema TTL#2972
Open
pcarleton wants to merge 5 commits into
Open
spec: decouple Mcp-Param-* header emission from schema TTL#2972pcarleton wants to merge 5 commits into
pcarleton wants to merge 5 commits into
Conversation
The Client Behavior note for custom Mcp-Param-* headers previously said clients SHOULD omit headers when the cached inputSchema is stale. With ttlMs: 0 this creates a loop: the schema is always stale, so the client always omits the header, the server rejects (header missing but value in body), the client refreshes tools/list, and the refreshed schema is still stale. Reframe the rule: clients use the most recently obtained inputSchema to construct headers, omit only when no schema has ever been obtained, and refresh-and-retry on reject (now covering both missing and mismatched headers). TTL governs re-fetch cadence for tools/list; it is not a gate on emitting routing headers. Server-side header/body validation is the freshness check.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com>
pcarleton
commented
Jun 24, 2026
Member
Author
|
from Core-Maintainers meeting:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The Client Behavior note for
Mcp-Param-*headers says clients SHOULD omit custom headers when the cachedinputSchemais stale. WithttlMs: 0this is internally inconsistent:Mcp-Param-*.tools/listand retry "with the appropriate headers".ttlMs: 0, so still stale, so per (1) the client still SHOULD omit. Loop.ttlMs: 0+x-mcp-headerisn't an unreasonable config (volatile tool list, stable routing needs), so "don't do that" isn't a satisfying answer.Change
Reframe the rule as optimistic-use-with-revalidation :
Mcp-Param-*headers from the most recently obtainedinputSchema, regardless of TTL.tools/listand retry.The server's mandatory header<>body validation is the freshness check for header emission; TTL governs
tools/listre-fetch cadence and doesn't need to gate header emission.This is equal-or-better than "omit when stale" in every drift case: