# 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. Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/modelcontextprotocol/typescript-sdk/issues/2721

```text
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: https://github.com/modelcontextprotocol/typescript-sdk/blob/951fe5603a7ec0b2dcb6a0b95d92cd86f93ad9e5/packages/core-internal/src/validators/dialects.ts#L58

## 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)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#schema-dialect)

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

```ts
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": []}
```

## 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](https://isokron.ai/mcp-check/checks/spec-schema-valid)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [No $ref to a network or external URI](https://isokron.ai/mcp-check/checks/spec-ref-remote)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

## Further reading

- [Shipping a production MCP server on the 2026-07-28 spec](https://isokron.ai/research/production-mcp-server)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
