MCP Error: Invalid outputSchema, JSON Schema Declares an Unsupported Dialect

If you build or run an MCP server on the MCP TypeScript SDK (@modelcontextprotocol/sdk) and one of its tools declares an outputSchema, there is a good chance a client somewhere is quietly rejecting every call to it. The tool shows up fine in tools/list. The server logs look healthy. And then tools/call fails with this:

Tool 'perplexity_search' 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.

Swap the tool name and it is the same story everywhere: Perplexity’s official MCP server hits it on all four of its tools, and — a bit awkwardly — so does the reference @modelcontextprotocol/server-filesystem running inside Claude Desktop. This is not one server’s bug, so there is no point hunting for it in yours.

The “unsupported dialect” error is a client-side schema validation failure: the client refuses to trust a tool’s outputSchema — the optional JSON Schema describing the tool’s structuredContent result — because its $schema names a JSON Schema dialect (draft-07) that the client’s validator does not support.

What causes the outputSchema draft-07 error in the MCP TypeScript SDK

Think of $schema as the language label on a parcel. The contents are perfectly readable, but the client’s customs desk only speaks 2020-12, sees “draft-07” on the label, and sends the parcel back unopened.

The label is stuck on by the SDK, not by you. In @modelcontextprotocol/sdk, zod-json-schema-compat.ts has a helper, mapMiniTarget(), that returns 'draft-7' whenever no explicit target is passed. McpServer’s tool-listing code calls the converter for both inputSchema and outputSchema — and never passes a target. So every schema gets stamped "$schema": "http://json-schema.org/draft-07/schema#", whatever Zod version you use (Zod v3 goes through zod-to-json-schema, which also defaults to draft-07). A client with a strict 2020-12-only validator sees that line on the outputSchema and refuses the call before your handler ever runs (issue #2721).

I checked this against the published 1.30.1 package rather than taking the issue’s word for it: a Zod v4 tool registered with McpServer comes back from tools/list with the draft-07 $schema on both schemas.

Strictly speaking, neither side is breaking the protocol on its own. The MCP specification’s JSON Schema rules say schemas without $schema default to 2020-12, schemas may declare another dialect, implementations must support at least 2020-12, and an unsupported dialect should produce a clear error — which is exactly what you are looking at. The SDK is simply declaring the one dialect that strict clients are allowed to refuse.

The same missing target was reported earlier, for both schemas, in issue #2084 against 1.29.0 — a regression of the SEP-1613 change that made 2020-12 the default. Issue #2084 is still open too.

Is there an SDK release that fixes the unsupported dialect error?

As of @modelcontextprotocol/sdk 1.30.1 (published on 23 September 2026), no release fixes this. Both candidate fixes are unmerged pull requests: PR #2085 (the SEP-1613 fix for the SDK’s v1.x line, which passes target: 'draft-2020-12' at both call sites) and PR #2653 (changing the Zod v4 fallback to draft-2020-12). Downgrading does not help either — the Perplexity maintainers note that bumping the SDK or moving to Zod v4 still emits draft-07.

Workaround 1: Remove outputSchema and keep returning structuredContent

Removing outputSchema is the stopgap suggested in the Perplexity server’s issue, and it is valid per the MCP tools specification, where outputSchema is optional. Your handler still returns structuredContent exactly as before:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "news", version: "1.0.0" });

// Keep the Zod schema: you still want it, just not in tools/list for now
const SearchResult = z.object({
  results: z.array(z.object({ title: z.string(), url: z.string() })),
});

server.registerTool(
  "search_news",
  {
    description: "Search the news archive",
    inputSchema: { query: z.string() },
    // outputSchema: SearchResult.shape,  // removed until the SDK emits 2020-12
  },
  async ({ query }) => {
    const structured = SearchResult.parse({
      results: [{ title: `Result for ${query}`, url: "https://example.com" }],
    });
    return {
      content: [{ type: "text", text: JSON.stringify(structured) }],
      structuredContent: structured,
    };
  }
);

I ran this against SDK 1.30.1: tools/list no longer advertises an outputSchema, and tools/call still returns the structured result. Two things you give up: clients no longer see the advertised shape, and the SDK stops validating your structuredContent for you (validateToolOutput() returns early when there is no outputSchema). That is why the snippet calls SearchResult.parse() itself.

Workaround 2: Patch mapMiniTarget() to emit JSON Schema 2020-12 with patch-package

If you would rather keep outputSchema, or your client also complains about inputSchema, do what some people on issue #2084 are doing: patch the fallback with patch-package until the fix ships. In both dist/esm/server/zod-json-schema-compat.js and dist/cjs/server/zod-json-schema-compat.js, change the first line of mapMiniTarget():

 function mapMiniTarget(t) {
     if (!t)
-        return 'draft-7';
+        return 'draft-2020-12';

Then run npx patch-package @modelcontextprotocol/sdk and add "postinstall": "patch-package" to your package.json scripts. With this patch, 1.30.1 emits https://json-schema.org/draft/2020-12/schema for both schemas in my test. The patch only covers Zod v4 schemas — the Zod v3 branch never calls mapMiniTarget() — and it is a patch to someone else’s code, so delete it the moment a fixed release lands.

Checklist: fixing “JSON Schema declares an unsupported dialect” in MCP

The client error says “unsupported dialect” and names draft-07? It is this bug, not your Zod types.
Check your SDK version: 1.30.1 and earlier are affected.
Need it working now with no dependency hacks? Drop outputSchema, keep returning structuredContent, validate it yourself.
Want to keep the schema? Patch mapMiniTarget() with patch-package (Zod v4 only).
Watch PR #2085 and PR #2653, then remove whichever workaround you used.

Final thoughts: tools/list success does not prove your MCP schemas are valid

tools/list succeeding is not proof your schemas are fine — the failure here only shows up one call later, and by then it looks like the server, not the SDK. If a tool with an outputSchema starts failing every call for no visible reason, read the client-side error for “unsupported dialect” before you go debugging your own Zod types. It will save you an evening.