SEP-834: Tools `inputSchema` & `outputSchema` conform to JSON Schema 2020-12 by jpmcb · Pull Request #881 · modelcontextprotocol/modelcontextprotocol

jpmcb · 2025-06-30T18:03:06Z

Motivation and Context

TLDR:

Loosens inputSchema to be an object with type: object and any additional property to support JSON schema Draft 2020-12 and more powerful validation compositions (like anyOf, oneOf, etc.)
Loosens outputSchema to fully support JSON Schema 2020-12 since MCP servers may return any valid JSON.
- Loosens structuredContent to support any JSON validated by outputSchema's JSON Schema.

Fixes: #834

Related to and upstream fix for:

This RFC loosens the restrictions on tool inputSchema and outputSchema in order to better fully support JSON Schema.

The specification currently states:

outputSchema: Optional JSON Schema defining expected output structure
inputSchema: JSON Schema defining expected parameters

which is not entierly true:

`inputSchema`

inputSchema is currently expected to be JSON Schema of type: object. This mostly makes sense since tool calls are expected to be well defined object key / values. This has been more accurately defined in the specification. Any additional property is now also acceptable to allow for much more powerful JSON Schema compositions (like with anyOf, oneOf, etc.)

`outputSchema` & `structuredContent`

outputSchema is also currently expected to be JSON schema of type: object which can cause some headaches for MCP servers that return other forms of JSON like arrays of objects:

[
  { "id": "abc123", "property": "hello" },
  { "id": "xyz987", "property": "world" }
]

In order to accommodate results that may be structured as an array (or really anything that can be validated by JSON Schema), outputSchema now is defined simply as an object.

This impacts structuredContent which was previously restricted to be an object: but, if outputSchema can validate any JSON, then structuredContent must be able to also be any valid JSON. Thus, it has been loosened to unknown.

How Has This Been Tested?

Tested in a weather application I'm building that returns a sorted array of weather hourly objects (see comment: #834 (comment))

Breaking Changes

No updates required. All existing type: object based schemas still work with JSON Schema. Not sure if this belongs in draft or would be better suited for 2025-06-18: I leave that to the maintainers.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

sambhav

LGTM

Mihailoff · 2025-07-09T02:12:47Z

+1

FastMCP just works, with MCP SDK I had a number of issues with schemas because of the confusing (input/output)Schema signature.

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
})

Also, https://modelcontextprotocol.io/docs/concepts/tools provide this example:

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

And then after reading spec you do the same and ... it doesn't work. Very confusing.

Mihailoff · 2025-07-09T02:28:22Z

olaservo · 2025-07-16T01:58:46Z

Hi @jpmcb, it looks like there is some overlap with my older PR here which addresses being more explicit about the JSON Schema dialect: #655

If we're replacing that PR with a new SEP based on this PR, should we also add explicit dialect support by using the $schema field?

jpmcb · 2025-07-17T14:10:26Z

Thanks for the reference @olaservo - yes, the overlap makes a ton of sense. I can create a new one that is based on the new SEP and I can include your changes and add you as a co-author on the commit?

jpmcb · 2025-07-21T21:34:28Z

cc @olaservo - I brought in 29b8528931520ccd021c51dde7d0ffb252f6ca10 from your PR and updated #834 to reflect a SEP. I'll get this ironed out and ready for review / sponsorship.

xlogix · 2025-09-08T15:41:17Z

Hi folks, any chance that this can be merged?

jpmcb · 2025-09-16T21:18:41Z

Squashed to 1 commit with Co-authored-by @olaservo
Resolved merge conflict
Addressed and applied feedback from @dsp-ant and @jonathanhefner
Added another example to the valid permissible JSON Schemas under ### Schema Validation

Not certain why the broken link checker in schema.mdx is failing: I re-generated the schema via npm run generate:schema but still get this broken link:

error Syntax error - Unable to parse specification/draft/schema.mdx - 264:270-264:271: Unexpected closing slash `/` in tag,
     expected an open tag first

which seems to be caused by a </section> that wasn't opened on line 264

Mintlify's Markdown parser treats dollar signs as special characters in some cases. The exact cause is not clear, but it might be related to MDX's [LaTeX support](https://mdxjs.com/guides/math/). An example of this behavior can be seen in the build failure for [modelcontextprotocol#881][], in which `npm run check:docs:links` failed to parse `schema.mdx` due to newly introduced `$schema` properties. This commit modifies the `schema.mdx` generator to HTML encode dollar signs, thus preventing such parse errors. [modelcontextprotocol#881]: modelcontextprotocol#881

jonathanhefner · 2025-09-16T21:50:46Z

Not certain why the broken link checker in schema.mdx is failing: I re-generated the schema via npm run generate:schema but still get this broken link:
error Syntax error - Unable to parse specification/draft/schema.mdx - 264:270-264:271: Unexpected closing slash `/` in tag,
     expected an open tag first
which seems to be caused by a </section> that wasn't opened on line 264

I believe that is due to the new $schema properties, though I'm 100% sure of the root cause. I've submitted #1485 which works around the issue.

findleyr · 2025-09-18T16:28:31Z

+1 this LGTM, and I think the clarity it adds will help mitigate confusion and inconsistency across SDKs. Thanks!

Do we expect this will land for the October spec?

Mintlify's Markdown parser treats dollar signs as special characters in some cases. The exact cause is not clear, but it might be related to MDX's [LaTeX support](https://mdxjs.com/guides/math/). An example of this behavior can be seen in the build failure for [#881][], in which `npm run check:docs:links` failed to parse `schema.mdx` due to newly introduced `$schema` properties. This commit modifies the `schema.mdx` generator to HTML encode dollar signs, thus preventing such parse errors. [#881]: #881

jpmcb · 2025-09-25T13:48:02Z

Thanks for the feedback @findleyr - current plan is to solicite more feedback from client and SDK implementers since a few of the core maintainers had concerns about the backwards compatibility of loosening the schema object requirement.

#834 (comment)

But, I 100% agree: to not adopt this would continue to cause confusion across clients, SDKs, and serves leading to drifts in how different implementers work.

* General guidance on using JSON Schema 2020-12 * Tools `inputSchema` conforms to JSON Schema 2020-12 as "type: object" * Tools `outputSchema` conforms to JSON Schema 2020-12 * Tools `structuredContent` can be any valid JSON (as it coforms to potentially provided `outputSchema`) * Elicitation `requestedSchema` aligns with JSON Schema 2020-12 Co-authored-by: olaservo <olahungerford@gmail.com> Signed-off-by: John McBride <jpmmcbride@gmail.com>

logseq-cldwalker · 2025-09-25T19:42:00Z

Adding another vote for conforming to json schema and allowing for a fix for modelcontextprotocol/typescript-sdk#685 . I just had to work the inputSchema limitation of not being able to pass an array of objects. Hopefully this PR gets reviewed soon as it would enable a number of workflows

errodrigues · 2025-09-25T19:54:35Z

I 2nd that

findleyr · 2025-09-25T20:52:13Z

@logseq-cldwalker are you saying you want to be able to accept array values as tool arguments? This proposal doesn't change inputSchema to be anything other than an "object", and I agree that doing so would probably cause issues for SDKs.

Frankly, I don't necessarily see the need to relax the requirement that outputSchema is an "object". If that is a point of concern from maintainers, perhaps we could move it to a separate proposal. Formalizing on 2020-12 is (in my opinion) the most important aspect of this SEP.

jpmcb · 2025-09-30T17:26:16Z

are you saying you want to be able to accept array values as tool arguments?

Yes.

This proposes conforming to JSON Schema 2020-12 which also, by proxy, requires us to loosen the inputSchema and outputSchema fields to be valid JSON schema 2020-12.

In my eyes, you cannot have one without the other.

The new spec would be:

inputSchema: {
  $schema?: string;
  [key: string]: any;
};

which conforms to JSON schema 2020-12 and allows for inputs like arrays of objects (a very common use case):

{
  "$schema": "http://json-schema.org/2020-12/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number"
      }
    },
    "required": ["id"]
  }
}

Forcing type: object severely limits the capabilities of enabling calling tools with more complex arguments.

jpmcb · 2025-10-29T14:31:25Z

MCP seems to be repeating history with what OpenAPI did: for years, they also only supported a subset of JSON schema, much to the frustration of the community. They even faced similar pain where they couldn't support arrays of objects:

Eventually, with OpenAPI 3.1 in 2021, they transitioned to fully supporting JSON schema:

The mismatch between OpenAPI JSON Schema-like structures and JSON Schema itself has long been a problem for users and implementers. Full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12 will not only save users much pain, but also ushers in a new standardised approach to schema extensions

https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released

I would strongly encourage the maintainers to act quickly and fully adopt JSON schema 2020-12 before adoption and misalignment becomes a bigger problem.

errodrigues · 2025-10-29T16:16:17Z

I 100% second that suggestion!

olaservo · 2025-11-12T01:35:00Z

Quick update: I wanted to help move this forward this round, but since this requires breaking modifications we wanted to ensure that we have a way to tag in enough client representation as part of the discussion. Despite adding more folks to the Client Implementers group and tagging people in Discord, we still hadn't seen enough engagement there to help validate breaking changes on the timeline needed for spec release.

Given this constraint, I've asked the maintainer group to help establish a better engagement model so we can actually have those conversations based on client maintainer feedback instead of general wariness of breaking changes. I think we can give this proposal a much fairer chance in the next round if we can create a better forum for that over the next couple months.

mikekistler · 2025-11-12T13:41:56Z

@olaservo How is this different from SEP-1613?

And I don't see SEP-834 in the list of accepted SEPs for the 2025-11-25 spec version, so is this something we (SDK maintainers) need to think about right now?

olaservo · 2025-11-12T13:52:21Z

@mikekistler SEP-1613 is making the target default JSON schema dialect explicit, and SEP-834 extends that to remove the limitations on schemas which only support a subset of JSON Schema. SEP-834 isn't currently planned for the next spec release.

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

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>

localden · 2026-01-21T07:22:10Z

@olaservo @jpmcb checking if this SEP is still relevant and whether you would like to move it forward? There is currently no sponsor assigned.

olaservo · 2026-01-21T12:14:20Z

Hi @dend @jpmcb - I have picked this one up again recently and drafted a version in the new SEP PR format here: #2106

Will post more in the Discord.

localden · 2026-01-21T19:48:14Z

Closing this PR as it's tracked in #2106.

@jpmcb

Updates the Author(s) line to credit John McBride (@jpmcb) as the original proposal author (PR modelcontextprotocol#881) and Ola Hungerford (@olaservo) as the current shepherd handling the SEP-1850 conversion and review-feedback revisions. Adds an authorship note above the abstract spelling out the lineage so readers don't conflate the two contributions.

@jpmcb

… 2020-12 (#2106) * feat: add SEP draft for full JSON Schema 2020-12 support 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 #834 Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: update author format in SEP-0000 document * fix: update sponsor name format in SEP-0000 document * SEP-834: Loosen schema type restrictions for full JSON Schema 2020-12 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: #834 Co-Authored-By: John McBride <jpmmcbride@gmail.com> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * SEP-834: Update reference implementation with weather forecast demo - 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> * Update SEP * SEP-2106: Rename file and update header per SEP-1850 - Renamed 0000-json-schema-2020-12.md to 2106-json-schema-2020-12.md - Updated SEP number to 2106 - Updated PR link to #2106 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix prettier formatting * Regenerate schema.mdx for draft spec changes * Align SEP with John's original PR #881 intent - 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> * Fix inputSchema to require type: "object" per original intent Aligns schema.ts with John's original PR #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> * Update SDK reference to 1.25.2-sep834.4 * Update server reference to 1.1.0-sep834.1 * Fix SEP-2106 self-references, examples, and add docs page - Replace "SEP-834" references with "SEP-2106" throughout - Update JSON-serialized content examples to model-friendly summaries - Add cross-references to #1906, TS SDK #1149, and SEP-2200 - Create docs/community/seps/2106-json-schema-2020-12.mdx Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Regenerate SEP docs via render-seps script Run `npm run generate:seps` to update index, docs.json, and .mdx to match the CI-expected output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix Prettier formatting in SEP-2106 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Regenerate schema.mdx from schema.ts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Address review feedback on SEP-2106 - seps: type code blocks now use `unknown` (matches schema definition) - seps: split Backward Compatibility into a directional matrix and document the source-breaking TypeScript widening for consumers - seps: expand Security Implications to require non-local `$ref`s not be auto-dereferenced (SSRF/fetch-DoS) and to bound composition cost - schema.ts: TSDoc on `inputSchema` calls out `type: "object"` root requirement and lists the JSON Schema 2020-12 keywords now allowed - example: add `type: "object"` at the root of the composition inputSchema example so it conforms to the spec - regenerate schema.json, schema.mdx, and SEP MDX * Format docs.json to match render-seps output The render-seps --check job rewrites docs.json via JSON.stringify (one element per array line) and compares raw. A prior prettier pass had collapsed short pages arrays onto single lines, which diverged from what the check expects. * Restore docs/community/seps/2243-http-standardization.mdx Upstream main keeps an orphaned copy of this SEP at the legacy docs/community/seps/ path alongside the canonical docs/seps/ one. Removing it during conflict resolution was unrelated cleanup that doesn't belong in this PR — restoring to match upstream. * Distinguish original author from current shepherd in SEP-2106 Updates the Author(s) line to credit John McBride (@jpmcb) as the original proposal author (PR #881) and Ola Hungerford (@olaservo) as the current shepherd handling the SEP-1850 conversion and review-feedback revisions. Adds an authorship note above the abstract spelling out the lineage so readers don't conflate the two contributions. * Re-fix docs.json after upstream merge The merge of upstream/main re-collapsed short pages arrays onto single lines in docs.json. The render-seps --check job compares docs.json byte-for-byte against JSON.stringify(d, null, 2) output (one element per line), so the collapsed form fails the check. Regenerated docs.json via JSON.stringify to restore the expected format. --------- Co-authored-by: John McBride <jpmmcbride@gmail.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Den Delimarsky <den@anthropic.com>

sambhav reviewed Jul 3, 2025

View reviewed changes

jpmcb mentioned this pull request Jul 15, 2025

SEP-834 Support full JSON Schema 2020-12 #834

Closed

jpmcb force-pushed the output-schema-fix branch from 6164798 to ea05ada Compare July 21, 2025 21:19

jpmcb requested a review from a team July 21, 2025 21:19

jpmcb force-pushed the output-schema-fix branch from 29b8528 to bec0be2 Compare August 12, 2025 22:35

jpmcb mentioned this pull request Aug 22, 2025

Tool inputSchema and outputSchema do not support JSON Schema modelcontextprotocol/typescript-sdk#685

Closed

dsp-ant changed the title ~~RFC: Tools inputSchema & outputSchema conform to JSON Schema 2020-12~~ SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 Sep 12, 2025

dsp-ant reviewed Sep 12, 2025

View reviewed changes

Comment thread docs/specification/draft/basic/index.mdx

jonathanhefner reviewed Sep 12, 2025

View reviewed changes

Comment thread docs/specification/draft/basic/index.mdx Outdated

Comment thread docs/specification/draft/basic/index.mdx Outdated

olaservo mentioned this pull request Sep 13, 2025

SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #655

Merged

5 tasks

jpmcb force-pushed the output-schema-fix branch 3 times, most recently from 27b2414 to d9cdb6a Compare September 16, 2025 21:06

jonathanhefner mentioned this pull request Sep 16, 2025

HTML encode dollar sign in schema reference #1485

Merged

jpmcb force-pushed the output-schema-fix branch from d9cdb6a to 8afdce3 Compare September 25, 2025 13:42

jpmcb force-pushed the output-schema-fix branch from 8afdce3 to 0b1c2b5 Compare September 25, 2025 15:01

olaservo mentioned this pull request Oct 6, 2025

SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

Closed

lawrencepit mentioned this pull request Oct 25, 2025

Output schema type array modelcontextprotocol/ruby-sdk#170

Closed

domdomegg requested a review from a team as a code owner November 25, 2025 19:37

dsp-ant added SEP proposal SEP proposal without a sponsor. labels Jan 14, 2026

olaservo mentioned this pull request Jan 17, 2026

SEP-2106: Tools inputSchema & outputSchema Conform to JSON Schema 2020-12 #2106

Merged

localden added this to SEP Review Pipeline Jan 21, 2026

localden closed this Jan 21, 2026

localden removed this from SEP Review Pipeline Jan 28, 2026

github-actions Bot mentioned this pull request Jan 29, 2026

[in-review] SEP-834: SEP-834 Support full JSON Schema 2020-12 joshrotenberg/tower-mcp#253

Closed

6 tasks

github-actions Bot mentioned this pull request Mar 9, 2026

[in-review] SEP-834: Support full JSON Schema 2020-12 joshrotenberg/tower-mcp#697

Closed

3 tasks

coderabbitai Bot mentioned this pull request Jun 6, 2026

Advertise MCP bounty list output schema ramimbo/mergework#1017

Open

coderabbitai Bot mentioned this pull request Jul 3, 2026

Stabilize memory context output (roadmap Sprint 1) besfeng23/Memory#123

Merged

Uh oh!

Conversation

jpmcb commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

inputSchema

outputSchema & structuredContent

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

sambhav left a comment

Choose a reason for hiding this comment

Uh oh!

Mihailoff commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mihailoff commented Jul 9, 2025

Uh oh!

olaservo commented Jul 16, 2025

Uh oh!

jpmcb commented Jul 17, 2025

Uh oh!

jpmcb commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xlogix commented Sep 8, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpmcb commented Sep 16, 2025

Uh oh!

jonathanhefner commented Sep 16, 2025

Uh oh!

findleyr commented Sep 18, 2025

Uh oh!

jpmcb commented Sep 25, 2025

Uh oh!

logseq-cldwalker commented Sep 25, 2025

Uh oh!

errodrigues commented Sep 25, 2025

Uh oh!

findleyr commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jpmcb commented Sep 30, 2025

Uh oh!

jpmcb commented Oct 29, 2025

Uh oh!

errodrigues commented Oct 29, 2025

Uh oh!

olaservo commented Nov 12, 2025

Uh oh!

mikekistler commented Nov 12, 2025

Uh oh!

olaservo commented Nov 12, 2025

Uh oh!

localden commented Jan 21, 2026

Uh oh!

olaservo commented Jan 21, 2026

Uh oh!

localden commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

jpmcb commented Jun 30, 2025 •

edited

Loading

`inputSchema`

`outputSchema` & `structuredContent`

Mihailoff commented Jul 9, 2025 •

edited

Loading

jpmcb commented Jul 21, 2025 •

edited

Loading

findleyr commented Sep 25, 2025 •

edited

Loading