Repository navigation
Conversation
The 2026-07-28 Streamable HTTP spec only allows x-mcp-header on a property reached from the schema root through "properties" keys. An annotation under items, a composition or conditional keyword, or a $ref target makes the tool definition invalid. validateParamHeaderAnnotations only looked at "properties", because headerSchemaProperty decodes nothing else. An annotation anywhere else was never seen, so Server.AddTool accepted the tool and the annotation was silently dropped. Walk the subschema keywords as well and report any x-mcp-header found under them. The walk uses the decoded JSON rather than new fields on headerSchemaProperty, since keywords like additionalProperties can be booleans and a typed field would make the whole decode fail. With this change Server.AddTool panics for such a tool, as it already does for the other invalid annotations, and ClientSession.ListTools drops it. New TestValidateToolParamHeaders cases cover items, oneOf, anyOf, allOf, not, if/then/else and a $defs entry reached through $ref; all seven fail without the change. Another case checks that a nested properties annotation next to unannotated subschemas is still accepted. Fixes modelcontextprotocol#1250 Signed-off-by: Swayam Mishra <swayyaam@gmail.com>
This branch has not been deployed
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
1 participant
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.
The spec only allows
x-mcp-headeron a property you can reach from the schema root throughpropertieskeys.validateParamHeaderAnnotationsonly ever looked atproperties, becauseheaderSchemaPropertydoesn't decode anything else. So an annotation underitems,oneOf/anyOf/allOf,not,if/then/elseor a$reftarget was silently accepted and then ignored.The fix walks the decoded schema and rejects any
x-mcp-headerfound under a subschema keyword (items,prefixItems,additionalProperties, the composition and conditional keywords,$defs, and so on). I went with walking the decoded JSON instead of adding typed fields toheaderSchemaProperty, because a boolean like"additionalProperties": falsewould make the typed decode fail, which would quietly turn off validation and header extraction for that tool.Behavior change:
Server.AddToolnow panics for these schemas, same as it already does for other invalid annotations. On the client side,ClientSession.ListToolsdrops them throughfilterValidTools.Tests: 7 new rejection cases in
TestValidateToolParamHeaders(items,oneOf,anyOf,allOf,not,if/then/else,$defsvia$ref) plus one case where a valid nestedpropertiesannotation sits next to unannotated subschemas and is still accepted. The 7 fail without the fix and pass with it. I also reverted the fix after writing it to confirm they go red again.go test ./...andgo vet ./...are clean.Fixes #1250
I used Claude Code to help find and fix this; I ran the tests and reviewed every line myself.