Skip to content

[Bug]: outputSchema declares draft-07 (inherited SDK default), making every tool unusable in Claude Code #1427

Open

Description

@amitfin

Version

2.1.0 (also reproduced on 2.0.0 and 1.14.0)

App

  • Other — Claude Desktop / Claude Code (macOS), app version 1.28929.0

Affected Models (if applicable)

  • Other — model-independent; fails before any model is involved

Bug Description

Every tool on this server is currently unusable in Claude Code / Claude Desktop. find, count, aggregate, and list-collections all fail identically, at tool-registration time, before any request reaches the server process:

Tool 'count' 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; pass a pre-configured Ajv instance to AjvJs

The client changed, not this server — I've filed that regression as anthropics/claude-code#86142. But the practical result today is that mongodb-mcp-server is 100% non-functional for Claude Code users, and there is a one-line change here that restores it.

Why this is different from #417

#417 asked you to remove or rename $schema, and was closed with:

"$schema is an internal field documented on the JsonSchema spec and it's standard so we are not willing to remove or rename it unless there is a really specific issue."

That reasoning is sound and I'm not contesting it. This request is not to remove $schema — it's to change which dialect it names. And the "really specific issue" now exists: a shipping client where every tool on this server is dead.

Root cause — it's an inherited default, not a deliberate choice

The draft-07 dialect isn't coming from your code. It comes from the MCP TypeScript SDK's default. In @modelcontextprotocol/[email protected], dist/esm/server/zod-json-schema-compat.js:

function mapMiniTarget(t) {
    if (!t)
        return 'draft-7';          // <-- default when no target is passed
    if (t === 'jsonSchema7' || t === 'draft-7')
        return 'draft-7';
    if (t === 'jsonSchema2019-09' || t === 'draft-2020-12')
        return 'draft-2020-12';
    return 'draft-7';              // <-- fallback
}

mongodb-mcp-server passes no target (I grepped dist/esm — no dialect string appears anywhere outside the bundled UI), so it inherits 'draft-7'. Under zod 4.4.3 that produces:

target: 'draft-7'        -> "http://json-schema.org/draft-07/schema#"
target: 'draft-2020-12'  -> "https://json-schema.org/draft/2020-12/schema"

Requested change

Pass target: 'draft-2020-12' when generating tool schemas. $schema stays present and standards-compliant; only the declared dialect changes. 2020-12 is also the current JSON Schema release and what most MCP clients assume.

The deeper fix belongs upstream — the SDK arguably shouldn't default to a 2019-era dialect — but that's a slower path, and this change unblocks your users now.

Steps to Reproduce

Configure the server in Claude Desktop and call any tool:

{
  "mongodb": {
    "command": "npx",
    "args": ["-y", "[email protected]", "--readOnly"],
    "env": { "MDB_MCP_CONNECTION_STRING": "mongodb://127.0.0.1:27017" }
  }
}

All tools fail with the error above; server logs show no incoming tools/call.

To observe the declared dialect independently of any client, this speaks JSON-RPC over stdio and prints it. No reachable database is needed — tools/list answers regardless:

import json, subprocess, sys, os

def probe(ver):
    env = dict(os.environ, MDB_MCP_CONNECTION_STRING="mongodb://127.0.0.1:27099/?serverSelectionTimeoutMS=200")
    p = subprocess.Popen(["npx", "-y", f"mongodb-mcp-server@{ver}", "--readOnly"],
        stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, env=env)
    def send(o): p.stdin.write(json.dumps(o) + "\n"); p.stdin.flush()
    send({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}})
    send({"jsonrpc":"2.0","method":"notifications/initialized"})
    send({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}})
    tools = None
    try:
        for _ in range(200):
            line = p.stdout.readline()
            if not line: break
            try: m = json.loads(line)
            except: continue
            if m.get("id") == 2:
                tools = m.get("result", {}).get("tools", []); break
    finally:
        p.kill()
    withos = [t for t in tools or [] if "outputSchema" in t]
    dialects = {t["outputSchema"].get("$schema", "<none>") for t in withos}
    return f"v{ver}: {len(tools or [])} tools, {len(withos)} with outputSchema, dialects={dialects or '-'}"

for v in sys.argv[1:]:
    print(probe(v))
$ python3 probe.py 1.14.0 2.0.0 2.1.0
v1.14.0: 16 tools, 13 with outputSchema, dialects={'http://json-schema.org/draft-07/schema#'}
v2.0.0:  18 tools, 15 with outputSchema, dialects={'http://json-schema.org/draft-07/schema#'}
v2.1.0:  18 tools, 15 with outputSchema, dialects={'http://json-schema.org/draft-07/schema#'}

Note that all versions emit the same dialect, including 1.14.0 — confirming the server behavior is long-standing and that the trigger was a client-side change.

Additional Context

Activity

  1. amitfin commented on Aug 12, 2026

    @amitfin
    Author

    Correction: the one-line fix is in the SDK, and nothing in this repo can be a one-liner

    I need to retract the "Requested change" in my original report. I wrote that this repo should pass target: 'draft-2020-12'. That is not reachable through the SDK's public API, so the suggestion was wrong — apologies for the noise.

    Why it isn't possible here

    Both conversion call sites hardcode their options, and target is never threaded through registerTool. From @modelcontextprotocol/sdk src/server/mcp.ts (v1.29.0 tag; the compiled 1.30.0 in node_modules is identical):

    // src/server/mcp.ts:151  — inputSchema
    ? (toJsonSchemaCompat(obj, {
          strictUnions: true,
          pipeStrategy: 'input'
      })
    
    // src/server/mcp.ts:165  — outputSchema
    toolDefinition.outputSchema = toJsonSchemaCompat(obj, {
        strictUnions: true,
        pipeStrategy: 'output'
    }) as Tool['outputSchema'];

    grep -n target src/server/mcp.ts returns nothing. The option exists on the CommonOpts type in the compat module but is never passed by, nor exposed to, server authors. So there is no option mongodb-mcp-server can set.

    The actual one-liner

    File: src/server/zod-json-schema-compat.ts (repo: modelcontextprotocol/typescript-sdk)
    Line: 25, inside mapMiniTarget

    function mapMiniTarget(t: CommonOpts['target'] | undefined): 'draft-7' | 'draft-2020-12' {
        if (!t) return 'draft-7';                       // <-- line 25, current
        if (t === 'jsonSchema7' || t === 'draft-7') return 'draft-7';
        if (t === 'jsonSchema2019-09' || t === 'draft-2020-12') return 'draft-2020-12';
        return 'draft-7'; // fallback
    }

    The change:

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

    That flips the default dialect for every SDK-based server, including this one, from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema. Verified against zod 4.4.3:

    target: 'draft-7'        -> "http://json-schema.org/draft-07/schema#"
    target: 'draft-2020-12'  -> "https://json-schema.org/draft/2020-12/schema"
    

    Caveat: line 25 governs inputSchema too, so this changes both. If a narrower blast radius is wanted, the equivalent single-line edit is at the outputSchema call site instead — add target: 'draft-2020-12' to the options object at src/server/mcp.ts:165, leaving inputSchema on draft-07.

    What this repo can realistically do

    Since no option is exposed, the choices here are all workarounds rather than one-liners:

    1. Wait on the upstream fix and bump the @modelcontextprotocol/sdk floor once it lands. Cleanest, but leaves Claude Code users broken meanwhile.
    2. Post-process tools/list — rewrite outputSchema.$schema to the 2020-12 URI (or delete the key) before the response goes out, via the low-level Server request handler rather than McpServer.registerTool.
    3. Temporarily stop declaring outputSchema. Restores every tool immediately in affected clients, at the cost of structured content.

    Option 2 is the one that keeps both structured output and current clients working, if you want a stopgap that doesn't wait on upstream.

    I'm happy to open the upstream SDK issue and reference this one, if that's the preferred routing.

  2. amitfin commented on Aug 12, 2026

    @amitfin
    Author

    Status update — fix is now upstream, little action needed here

    I've opened modelcontextprotocol/typescript-sdk#2653 against the v1.x branch, which changes the Zod v4 conversion default (and the unrecognised-target fallback) from draft-7 to draft-2020-12. Full suite passing, lint clean.

    If that lands and ships as a 1.30.x patch, this repo picks it up with no code change: the dependency here is @modelcontextprotocol/sdk: ^1.29.0, unbundled, so npm resolves the newest 1.x at install time.

    Two things that would still help your users, though — so this isn't purely an upstream wait:

    1. Cut a release once the SDK patch is out. Many users run this via npx -y mongodb-mcp-server@latest. npx reuses its cached tree while the resolved top-level version is unchanged, so an SDK-only patch won't reach anyone already on 2.1.0 until a new mongodb-mcp-server version invalidates that cache (or they clear ~/.npm/_npx manually). A version bump — even a trivial one — is what actually delivers the fix.

    2. Optionally bump the floor to the fixed SDK version once known, so the dialect is guaranteed rather than incidental.

    If you'd rather track this purely upstream, closing in favour of the SDK PR is completely reasonable — I mainly want the diagnosis discoverable here, since anyone hitting "every MongoDB MCP tool fails in Claude Code" will search this repo first.

  3. Ooscaar commented on Aug 13, 2026

    @Ooscaar

    Workarund for now is to run the the mongo MCP server with 1.13.0 version.

  4. self-assigned this
    on Aug 14, 2026
  5. gagik commented on Aug 14, 2026

    @gagik
    Collaborator

    As far as I can see people are experiencing this across many MCP servers in Claude Code so the issue seems to originate from the harness itself.

    Going to keep this open until upstream is resolved but don't see any actionable steps from our end beyond downgrading (which wouldn't make sense).

  6. cid2230 commented on Sep 10, 2026

    @cid2230

    Hi — Exactlane Operations here. We’re running a small Phase 0 experiment on caller-specific MCP compatibility.

    This issue is very close to the class of problem we’re testing: a capability/schema can be valid at the protocol level, while a specific host or client accepts a narrower schema dialect.

    Our current experiment is static-only:

    caller requirements × immutable tools/list snapshot
    → bounded compatibility report

    For this case, the specific question would be whether bounded caller requirements that encode the documented Claude Code draft-07 / 2020-12 dialect constraint could flag the outputSchema incompatibility before the integration reaches the host.

    We’re not reporting a current mongodb-mcp-server bug, and we understand the underlying restriction may be client/SDK-side.

    Would a check like that have been useful in this issue or on future client/SDK bumps?

    If so, we’d be happy to test one redacted snapshot from a real revision and send back the result for comparison with your current workflow. No live probing, production credentials, or sensitive task data.

    This is free Phase 0 research. If it isn’t useful or isn’t appropriate for this thread, no action needed.

    — Exactlane Operations

  7. github-actions commented on Oct 11, 2026

    @github-actions
    Contributor

    This issue has gone 30 days without any activity and meets the project's definition of "stale". This will be auto-closed if there is no new activity over the next 30 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions