SEP-2106: Tools inputSchema & outputSchema Conform to JSON Schema 2020-12#2106
Merged
mcp-commander[bot] merged 29 commits intoMay 18, 2026
Merged
Conversation
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 <[email protected]> Co-Authored-By: Claude Opus 4.5 <[email protected]>
… 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 <[email protected]> Co-Authored-By: Claude Opus 4.5 <[email protected]>
- 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/[email protected] - Server: @olaservo/[email protected] Co-Authored-By: Claude Opus 4.5 <[email protected]>
- 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 <[email protected]>
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 <[email protected]> Co-Authored-By: Claude Opus 4.5 <[email protected]>
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 <[email protected]> Co-Authored-By: Claude Opus 4.5 <[email protected]>
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. |
5 tasks
This was referenced May 26, 2026
Open
Closed
4 tasks
This was referenced Jun 6, 2026
9 tasks
koic
added a commit
to modelcontextprotocol/ruby-sdk
that referenced
this pull request
Jun 24, 2026
## Motivation and Context SEP-2106 (modelcontextprotocol/modelcontextprotocol#2106, merged for the 2026-07-28 spec release) makes tool `inputSchema` and `outputSchema` conform to the full JSON Schema 2020-12 vocabulary: an input schema keeps `type: "object"` at the root but may use any 2020-12 keyword below it; an output schema may be ANY valid schema (object, array, primitive, or a root-level composition); and `CallToolResult.structuredContent` widens from an object to any JSON value. The SEP also adds resource bounds: `$ref` resolution is restricted (same-document only in the reference implementation) and composition-heavy documents must be bounded to avoid excessive validation cost. This follows the TypeScript SDK's reference implementation (typescript-sdk#2249; the Python SDK tracks the same work in python-sdk#2792): - `Tool::Schema` now validates against the JSON Schema 2020-12 metaschema rather than the draft-04 metaschema. The draft-04 pin was a stopgap from when the SDK used the `json-schema` gem, which did not support 2020-12; `json_schemer` does, so `$defs`/`$ref` and the rest of the 2020-12 vocabulary now resolve natively. This matches the dialect the SDK already advertises in emitted schemas and the Python SDK's behavior, whose `jsonschema.validate` selects the validator from the schema's `$schema`. - `Tool::Schema` moves root-type defaulting into an overridable `apply_default_root_type!` hook. `InputSchema` keeps the historical `type: "object"` default; `OutputSchema` now applies it only when no root schema keyword (`type`, `$ref`, `oneOf`, `anyOf`, `allOf`, `not`, `if`, `const`, `enum`) is present. The previous unconditional default merged `type: "object"` into root combinators such as `{ oneOf: [...] }`, producing a wrong schema, so that case is a bug fix. - `Tool::Schema` enforces the TypeScript SDK's schema bounds at construction time: only same-document `$ref`/`$dynamicRef`s (starting with `#`, so schema handling can never trigger network or file access), `MAX_SCHEMA_DEPTH = 64` nesting levels, and `MAX_SUBSCHEMA_COUNT = 10_000` subschema objects, all raising `ArgumentError` on violation. - `Server#call_tool` mirrors non-object `structuredContent` into `content` as serialized JSON text when the tool provided no content blocks, so pre-SEP clients that only read `content` still receive the data. Object results and explicit content are untouched. Resolves #377. ## How Has This Been Tested? - `test/mcp/tool/output_schema_test.rb`: root-level `oneOf`, `$ref`+`$defs`, primitive, and `enum` schemas serialize without an injected `type` and validate results correctly; the `properties`-only shorthand still serializes with `type: "object"` (wire-format regression); explicit `type: "array"` keeps working. - `test/mcp/tool/input_schema_test.rb`: an input schema using `$defs`, `$ref`, `oneOf`, `if`/`then`, and `allOf` keeps its object root and round-trips all keywords; a draft-04-only boolean `exclusiveMinimum` is rejected under the 2020-12 dialect while the numeric form is accepted. - `test/mcp/tool/schema_test.rb`: depth and subschema-count bound violations raise `ArgumentError`; non-same-document `$ref`s (remote URI, sibling file) are rejected while `#/$defs/...` is accepted. The previous unbounded-depth caching test is replaced, since the depth bound now rejects such documents by design. - `test/mcp/server_test.rb`: `tools/call` with array `structuredContent` and no content gains the serialized TextContent fallback; explicit content is not overwritten; object `structuredContent` gets no fallback. `bundle exec rake` (tests, RuboCop, and conformance baseline, including the `json-schema-2020-12` server scenario) passes. ## Breaking Changes Three narrow behavior changes, all intentional per the SEP: - Runtime validation now uses the JSON Schema 2020-12 metaschema instead of draft-04. Schemas that rely on draft-04-only syntax are rejected at construction time. The practical case is the boolean `exclusiveMinimum`/`exclusiveMaximum` form (deprecated since draft-06), which must now be the numeric form; the Python SDK rejects it the same way. Other draft-04 spellings (`definitions`, `id`, `dependencies`) still validate, since 2020-12 tolerates unknown keywords. - Schemas that exceed the new resource bounds (nesting deeper than 64, more than 10,000 subschema objects) or use a non-same-document `$ref`/`$dynamicRef` now raise `ArgumentError` at construction time. Previously such documents were accepted (external references were already never fetched, only ignored). - An `OutputSchema` whose root declares a schema keyword other than `type` (e.g. `oneOf`) no longer has `type: "object"` merged into it. The old output was an invalid hybrid schema, so no conforming consumer could have relied on it.
9 tasks
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
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 2020-12 keywords — composition (oneOf/anyOf/allOf/not), conditional (if/then/else), reference ($ref/$defs/$anchor), 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:
#2455:$refschemas withouttype: objectbroke ALL tools on a server#2421: Unexpected{"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 Compatibility
The change is wire-format backward compatible, but compatibility is directional:
structuredContent. Arrays/primitives may break old clientsTo stay interoperable with old clients, servers using array or primitive
structuredContentMUST also emit aTextContentblock with the serialized JSON.Source-breaking for typed SDKs: Widening
structuredContentfrom{ [key: string]: unknown }tounknownbreaks property access on typed consumers without narrowing guards. The SEP includes migration guidance for SDK maintainers.Security Implications
Allowing the full JSON Schema 2020-12 vocabulary surfaces two areas covered explicitly in the SEP:
$refSSRF: Implementations MUST NOT automatically dereference$refURIs that aren't same-document JSON Pointers (e.g.#/$defs/Foo). Opt-in modes for fetching external$refs MUST default off and SHOULD enforce host allowlists, timeouts, size limits, and reject loopback/link-local/private addresses.Reference Implementation
@olaservo/[email protected](source)@olaservo/[email protected](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. Recent revisions addressing review feedback (asymmetric compat matrix, TypeScript migration guidance,
$refSSRF / composition-DoS security implications, and the reference example fix) were paired with 🦉 Claude Opus 4.7 (1M context).Related issue: #834
Original proposal: #881