Repository navigation
Description
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:
"
$schemais 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
- Client-side regression: MCP servers declaring draft-07 outputSchema are entirely unusable: "unsupported dialect" rejected client-side before dispatch anthropics/claude-code#86142
- Prior, differently-scoped request: [Bug]: The "schema" field in the input schema needs to be modified or removed #417 (internal ref MCP-101)
- Because the dialect comes from the SDK default, this likely affects many MCP servers built on the TypeScript SDK with zod v4 that declare
outputSchemawithout an explicit target —mongodb-mcp-serveris just a highly visible instance.
Activity
amitfin commentedon Aug 12, 2026
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
targetis never threaded throughregisterTool. From@modelcontextprotocol/sdksrc/server/mcp.ts(v1.29.0 tag; the compiled 1.30.0 innode_modulesis identical):grep -n target src/server/mcp.tsreturns nothing. The option exists on theCommonOptstype in the compat module but is never passed by, nor exposed to, server authors. So there is no optionmongodb-mcp-servercan set.The actual one-liner
File:
src/server/zod-json-schema-compat.ts(repo:modelcontextprotocol/typescript-sdk)Line: 25, inside
mapMiniTargetThe change:
That flips the default dialect for every SDK-based server, including this one, from
http://json-schema.org/draft-07/schema#tohttps://json-schema.org/draft/2020-12/schema. Verified against zod 4.4.3:Caveat: line 25 governs
inputSchematoo, so this changes both. If a narrower blast radius is wanted, the equivalent single-line edit is at theoutputSchemacall site instead — addtarget: 'draft-2020-12'to the options object atsrc/server/mcp.ts:165, leavinginputSchemaon draft-07.What this repo can realistically do
Since no option is exposed, the choices here are all workarounds rather than one-liners:
@modelcontextprotocol/sdkfloor once it lands. Cleanest, but leaves Claude Code users broken meanwhile.tools/list— rewriteoutputSchema.$schemato the 2020-12 URI (or delete the key) before the response goes out, via the low-levelServerrequest handler rather thanMcpServer.registerTool.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.
amitfin commentedon Aug 12, 2026
Status update — fix is now upstream, little action needed here
I've opened modelcontextprotocol/typescript-sdk#2653 against the
v1.xbranch, which changes the Zod v4 conversion default (and the unrecognised-target fallback) fromdraft-7todraft-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:
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 newmongodb-mcp-serverversion invalidates that cache (or they clear~/.npm/_npxmanually). A version bump — even a trivial one — is what actually delivers the fix.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.
Ooscaar commentedon Aug 13, 2026
Workarund for now is to run the the mongo MCP server with
1.13.0version.gagik commentedon Aug 14, 2026
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).
cid2230 commentedon Sep 10, 2026
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/listsnapshot→ 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
outputSchemaincompatibility 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
github-actions commentedon Oct 11, 2026
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!