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: Keep type: "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 by outputSchema
• Include reference implementations: TypeScript SDK fork and demo server with example tools

Motivation

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:

• Issue #2455: $ref schemas without type: object broke ALL tools on a server
• Issue #2421: Unexpected {"result": ...} wrapping confused users

Industry 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:

To stay interoperable with old clients, servers using array or primitive structuredContent MUST also emit a TextContent block with the serialized JSON.

Source-breaking for typed SDKs: Widening structuredContent from { [key: string]: unknown } to unknown breaks 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:

• $ref SSRF: Implementations MUST NOT automatically dereference $ref URIs 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.
• Composition cost: Implementations SHOULD bound schema depth, total subschemas, and per-validation time to prevent a malicious tool definition from acting as a CPU DoS vector.

Reference Implementation

• SDK: @olaservo/mcp-sdk@1.25.2-sep834.4 (source)
• Demo Server: @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 output
• find-by-id-or-name: Flexible input patterns using oneOf with type: "object"

AI disclosure

This PR was written with assistance from Claude. Recent revisions addressing review feedback (asymmetric compat matrix, TypeScript migration guidance, $ref SSRF / composition-DoS security implications, and the reference example fix) were paired with 🦉 Claude Opus 4.7 (1M context).

Related issue: #834
Original proposal: #881