modelcontextprotocol / modelcontextprotocol/typescript-sdk
outputSchema always emitted as JSON Schema draft-07, breaking clients that only accept 2020-12
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 13.4k
- Forks
- 2.2k
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 4
Description
Package: @modelcontextprotocol/sdk 1.30.0
Affects: any server built with McpServer that declares an outputSchema (e.g. @modelcontextprotocol/server-filesystem 2026.7.10), consumed by a client with a strict output-schema validator.
Bug
In src/server/zod-json-schema-compat.ts (compiled to dist/{cjs,esm}/server/zod-json-schema-compat.js), mapMiniTarget() falls back to 'draft-7' whenever no explicit target is passed:
function mapMiniTarget(t) {
if (!t) return 'draft-7'; // <-- always hit in practice
...
}
McpServer's tool-listing handler (src/server/mcp.ts) never passes a target when calling toJsonSchemaCompat() for either inputSchema or outputSchema:
toolDefinition.outputSchema = toJsonSchemaCompat(obj, {
strictUnions: true,
pipeStrategy: 'output'
});
So every registered tool's outputSchema (Zod v4 branch, via zod/v4-mini's toJSONSchema) is emitted with "$schema": "http://json-schema.org/draft-07/schema#", with no way for the server author to opt into 2020-12.
Impact
A client that validates outputSchema strictly against JSON Schema 2020-12 rejects every tool from every SDK-based server that declares an outputSchema, e.g. (observed in Claude Desktop 1.37937.1):
Tool 'list_directory' has an invalid outputSchema: JSON Schema declares an unsupported dialect
("$schema": "http://json-schema.org/draft-07/schema#"). The default validator supports JSON Schema 2020-12 only.
This breaks @modelcontextprotocol/server-filesystem entirely — every tool call fails client-side before even reaching the server.
Suggested fix
Default mapMiniTarget's fallback to 'draft-2020-12' instead of 'draft-7' (2020-12 is a superset-compatible, more current dialect and z4mini.toJSONSchema already supports it via the existing branch), or have McpServer pass target: 'draft-2020-12' explicitly.
Confirmed locally that swapping the fallback produces "$schema": "https://json-schema.org/draft/2020-12/schema" and resolves the client-side rejection with no other code changes needed.
Repro
- Any MCP server built with
McpServer+outputSchema(e.g.server-filesystem@2026.7.10). - A client validating
outputSchemastrictly against 2020-12 (e.g. Claude Desktop 1.37937.1+). - Every tool call fails with the "unsupported dialect" error above.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in src/server/zod-json-schema-compat.ts by reading mapMiniTarget(), then inspect the tool-listing handler in src/server/mcp.ts where toJsonSchemaCompat() is called. Reproduce a tool with an outputSchema and inspect the emitted $schema value; done means the listing emits the JSON Schema 2020-12 dialect and no longer triggers the strict client rejection described in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100