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

• What's the official scheme for inputSchema? #513
• Improve JSON Schema explanation and add reference link in "Tool definition structure" section #508
• https://github.com/orgs/modelcontextprotocol/discussions/366

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?

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?

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

Hi folks, any chance that this can be merged?

• 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

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.

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

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.

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

I 2nd that

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

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.

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:

• Make schema object compatible with JSON Schema draft4 OAI/OpenAPI-Specification#333
• JSON Schema for the OpenAPI 3.0 Specification OAI/OpenAPI-Specification#1032

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.

I 100% second that suggestion!

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.

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

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