Skip to content
IsoKron

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

Error
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

Error
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).

  1. Remove "$schema" from inputSchema and outputSchema (2020-12 is the default), or set it to https://json-schema.org/draft/2020-12/schema.
  2. Convert keywords that changed: items as an array becomes prefixItems, definitions becomes $defs.
  3. If a schema generator emits draft-07, configure its target or upgrade it (zod-to-json-schema, older Pydantic).

TypeScript SDK

TypeScript
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

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

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