Schemas use JSON Schema 2020-12
Since revision 2025-11-25 (SEP-1613) MCP clients only have to support JSON Schema 2020-12, so a schema that declares draft-07 (or older) in $schema can be refused with "JSON Schema declares an unsupported dialect"; remove $schema or set it to 2020-12.
Check spec-schema-dialect · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
Error message you’ll see
Tool 'list_directory' has an invalid outputSchema: JSON Schema declares an unsupported dialect […]Claude Desktop and Claude Code, for a draft-07 outputSchema. Where this was reported
JSON Schema declares an unsupported dialect ("$schema": "[…]"). The default validator supports JSON Schema 2020-12, 2019-09, draft-07, and draft-06; […]TypeScript SDK 2.4.0 validator. Where this message comes from
What fails
The schema declares another dialect with $schema. Clients only have to support 2020-12, so a client may answer that the dialect is not supported. This check validated the schema structurally only.
The rule
Implementations MUST support at least 2020-12 and SHOULD document which additional dialects they support
Source: MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons)
How to fix it
Remove $schema (2020-12 is the default) or set it to https://json-schema.org/draft/2020-12/schema, and adjust keywords that changed (for example items arrays become prefixItems).
- Remove "$schema" from inputSchema and outputSchema (2020-12 is the default), or set it to https://json-schema.org/draft/2020-12/schema.
- Convert keywords that changed: items as an array becomes prefixItems, definitions becomes $defs.
- If a schema generator emits draft-07, configure its target or upgrade it (zod-to-json-schema, older Pydantic).
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'list_directory',
{
title: 'List directory',
description: 'List the entries of one directory. Use when the user asks what a folder contains.',
inputSchema: z.strictObject({
path: z.string().describe('Directory path relative to the workspace root'),
}),
outputSchema: z.object({
entries: z.array(z.string()).describe('Entry names'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ path }) => {
const result = { entries: [] };
return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
},
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
from typing import TypedDict
server = MCPServer("issues")
class Result(TypedDict):
entries: list[str]
@server.tool(
title="List directory",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_directory(
path: Annotated[str, Field(description="Directory path relative to the workspace root")],
) -> Result:
"""List the entries of one directory. Use when the user asks what a folder contains."""
return {"entries": []}Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Why did my server stop working in Claude after an update?
Claude clients began validating outputSchema dialects. A server whose SDK emitted "$schema": "http://json-schema.org/draft-07/schema#" had its tools rejected. Current SDKs emit 2020-12.
Is draft-07 forbidden by the specification?
No. Since revision 2025-11-25 (SEP-1613, kept in 2026-07-28) implementations MUST support 2020-12 and SHOULD document others. A client may support draft-07 but does not have to, so 2020-12 is the safe choice.
Related checks
- inputSchema and outputSchema are valid JSON Schema
- Read tools declare an outputSchema
- No $ref to a network or external URI
- All checks in MCP tool input and output schemas
Further reading
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere