SEP-2106: Tools inputSchema & outputSchema Conform to JSON Schema 2020-12
#2106
+513
−69
Conversation
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
876b01c to
0d23ecc
Compare
Add SEP proposing to loosen inputSchema, outputSchema, and structuredContent restrictions to enable full JSON Schema 2020-12 compliance. This allows array responses and schema composition keywords (anyOf, oneOf, allOf). Relates to modelcontextprotocol#834 Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
… support - inputSchema: Allow any valid JSON Schema (enables oneOf/anyOf/allOf at root) - outputSchema: Allow any valid JSON Schema (enables array schemas) - structuredContent: Allow any JSON value (enables array responses) - Update tools.mdx documentation - Add example files demonstrating new capabilities Reference: modelcontextprotocol#834 Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Updated inputSchema spec to allow any valid JSON Schema (full 2020-12 compliance) - Replaced get-array-content with get-weather-forecast tool - Weather forecast matches the exact example from Motivation section - Updated npm package references to latest versions: - SDK: @olaservo/mcp-sdk@1.25.2-sep834.3 - Server: @olaservo/mcp-server-everything-sep834@1.1.0 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Renamed 0000-json-schema-2020-12.md to 2106-json-schema-2020-12.md - Updated SEP number to 2106 - Updated PR link to modelcontextprotocol#2106 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
9eb42d9 to
7250539
Compare
- Update title to match original: "Tools inputSchema & outputSchema Conform to JSON Schema 2020-12" - inputSchema: Keep type: "object" required, but allow additional JSON Schema properties - outputSchema: Fully flexible (any valid JSON Schema) - structuredContent: Any JSON value (unknown) - Update examples to show composition with type: "object" Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
inputSchema & outputSchema Conform to JSON Schema 2020-12
Aligns schema.ts with John's original PR modelcontextprotocol#881: - inputSchema: Keep type: "object" required, allow additional properties - outputSchema: Any valid JSON Schema (with $schema field) - Regenerate schema.json and schema.mdx Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
9 tasks
SamMorrowDrums
approved these changes
Feb 5, 2026
Maintainer Activity CheckHi @olaservo! You're assigned to this SEP but there hasn't been any activity from you in 14 days. Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer. This is an automated message from the SEP lifecycle bot. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 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.
Summary
Note: This PR converts John McBride's original SEP proposal (PR #881) from issue #834 to the new SEP format established by SEP-1850. The original proposal and community discussion remain in PR #881—this PR formalizes it under the new process with a reference implementation.
inputSchema: Keeptype: "object"required (since tool arguments are objects), but allow any additional JSON Schema properties to support composition keywords (anyOf,oneOf,allOf, etc.)outputSchema: Fully support JSON Schema 2020-12 (arrays, primitives, objects, compositions)structuredContent: Accept any JSON value validated byoutputSchemaMotivation
The current MCP specification restricts tool schemas in ways that conflict with full JSON Schema support and create real friction in the ecosystem.
The Problem: A weather API tool that returns hourly forecasts cannot return the natural response:
[ { "hour": "09:00", "temp": 68, "conditions": "sunny" }, { "hour": "10:00", "temp": 72, "conditions": "partly cloudy" } ]Instead, developers must wrap arrays in unnecessary container objects—conflicting with common REST API patterns (GitHub Events API, AccuWeather, standard collection endpoints).
SDK Evidence: This isn't theoretical friction. FastMCP, one of the most popular Python SDKs, has implemented extensive workarounds with error messages that explicitly cite "MCP spec limitations." These workarounds have caused real bugs:
$refschemas withouttype: objectbroke ALL tools on a server{"result": ...}wrapping confused usersIndustry Precedent: OpenAPI went through this same evolution. OpenAPI 3.0's "extended subset" of JSON Schema caused years of tooling confusion. OpenAPI 3.1 made the strategic decision to fully align with JSON Schema 2020-12—MCP can learn from this rather than repeating the same journey.
Backward Compatible: All existing schemas continue to work. No migration required.
Related issue: #834
Original proposal: #881
Reference Implementation
@olaservo/mcp-sdk@1.25.2-sep834.4(source)@olaservo/mcp-server-everything-sep834@1.1.0-sep834.1(source)Testing
Reference implementation tested with demo tools demonstrating:
get-weather-forecast: Raw array output (matches SEP motivation example)get-count: Raw primitive outputfind-by-id-or-name: Flexible input patterns usingoneOfwithtype: "object"AI disclosure
This PR was written with assistance from Claude. The SEP content, reference implementations, and rationale were developed collaboratively.