schemaToJson() produces $ref in tool inputSchema, causing LLM failures

[gogakoreli]

Description

schemaToJson() returns JSON Schema with $ref pointers for registered types (z.globalRegistry) and recursive types (z.lazy). LLMs consuming tool inputSchema cannot resolve $ref — they treat referenced parameters as untyped and serialize objects as string literals:

Expected: "parent": {"database_id": "2275ad9e-..."}
Received: "parent": "{\"database_id\":\"2275ad9e-...\"}"
→ Server rejects: MCP error -32602: Invalid arguments: expected object, received string

This is related to #1175 (AJV failing on $ref in tool schemas) — same root cause ($ref in inputSchema), different symptom (LLM stringification vs validator error).

Reproduction

import * as z from 'zod/v4';
import { schemaToJson } from '@modelcontextprotocol/core';

const Address = z.object({ street: z.string(), city: z.string() });
z.globalRegistry.add(Address, { id: 'Address' });

console.log(JSON.stringify(schemaToJson(z.object({ home: Address, work: Address }), { io: 'input' }), null, 2));

Output contains $ref instead of inline types:

{
  "properties": {
    "home": { "$ref": "#/$defs/Address" },
    "work": { "$ref": "#/$defs/Address" }
  },
  "$defs": { "Address": { "type": "object", ... } }
}

Context

$ref in tool schemas has always been possible — the old zod-to-json-schema library used $refStrategy: "root" by default (identity-based deduplication on second encounter of the same JS object). However, #1460's switch to z.toJSONSchema() widened the blast radius significantly: registered types produce $ref even on first and only use, and all recursive types produce $ref.

Confirmed across Claude Code (anthropics/claude-code#18260) and Kiro CLI (independently).

Proposed fix

Add a dereferenceLocalRefs() step to schemaToJson() that inlines all local $ref pointers and strips $defs/definitions. ~95 lines, zero external dependencies.

I already have a working implementation with tests — wanted to file the issue for discussion before submitting the PR per contributing guidelines. Happy to submit if this approach looks right.

[sstklen]

Hey! I ran into a similar pattern in our bug knowledge base and thought this might help.

What's happening: schemaToJson() (introduced via #1460's switch to Zod v4's built-in z.toJSONSchema()) emits $ref pointers for types registered in z.globalRegistry and for recursive z.lazy schemas. LLMs consuming tool inputSchema have no JSON Schema $ref resolver — they see {"$ref": "#/$defs/Address"} as an opaque string-typed field, so they serialize the object value as a JSON string literal instead of a nested object. The MCP server's argument validator then rejects it: 'expected object, received string'.

What worked for us:

Post-process the output of schemaToJson() (or z.toJSONSchema()) to inline/dereference all $ref pointers before returning the tool's inputSchema. Walk the schema tree, replace every {"$ref": "#/$defs/Foo"} node with the actual definition from $defs, then strip the now-unused $defs block. For recursive schemas, set a max-depth cutoff to avoid infinite expansion. Alternatively, pass a Zod v4 option to suppress $ref emission (if available), or reintroduce zod-to-json-schema with {$refStrategy: 'none'} for tool schema generation specifically.

Steps:

1. Create a dereferenceSchema(schema) utility that recursively walks JSON Schema and replaces {"$ref": "#/$defs/X"} nodes with the inlined definition from schema.$defs[X]
2. Handle recursive $ref cycles by tracking visited refs and capping expansion depth (e.g., 3 levels) to prevent infinite loops
3. Call dereferenceSchema() on the output of schemaToJson() inside the tool registration / listTools handler before returning inputSchema to the client
4. After inlining, delete the top-level $defs key since all references are now resolved inline
5. Add tests: (a) z.globalRegistry registered type produces inline schema without $ref, (b) z.lazy recursive type expands to max depth without $ref, (c) LLM-style consumer can parse the resulting schema correctly

// src/utils/dereference-schema.ts
export function dereferenceSchema(schema: Record<string, any>, maxDepth = 10): Record<string, any> {
  const defs = schema.$defs || schema.definitions || {};

  function resolve(node: any, depth: number, visiting: Set<string>): any {
    if (!node || typeof node !== 'object' || depth > maxDepth) return node;
    if (Array.isArray(node)) return node.map(n => resolve(n, depth, visiting));

    if (node.$ref && typeof node.$ref === 'string') {
      const match = node.$ref.match(/^#\/\$defs\/(.+)$/) || node.$ref.match(/^#\/definitions\/(.+)$/);
      if (match && defs[match[1]]) {
        if (visiting.has(match[1])) return {}; // break cycle
        visiting.add(match[1]);
        const inlined = resolve(structuredClone(defs[match[1]]), depth + 1, visiting);
        visiting.delete(match[1]);
        return inlined;
      }
      return node;
    }

    const result: Record<string, any> = {};
    for (const [key, value] of Object.entries(node)) {
      if (key === '$defs' || key === 'definitions') continue;
      result[key] = resolve(value, depth, visiting);
    }
    return result;
  }

  return resolve(schema, 0, new Set());
}

// Usage in tool schema generation:
// const rawSchema = schemaToJson(zodSchema, { io: 'input' });
// const inputSchema = dereferenceSchema(rawSchema);
// return { name, description, inputSchema };

📊 We found 1 similar case in our knowledge base with the same pattern — this gives us medium confidence in this analysis.

Hope this helps! Let me know if it doesn't match your case — happy to dig deeper. 🦞

Disclosure: This analysis is from Confucius Debug, an AI-powered community KB for agent bugs. Please verify before applying.

---

_{🦞 Confucius Debug — community knowledge base for AI agent bugs. Free to search via MCP.}

[MukundaKatta]

Confirming this is the same root cause on the Python SDK side — pydantic's model_json_schema() emits the same $ref/$defs shape and downstream LLM clients fail the exact way described here. Just opened modelcontextprotocol/python-sdk#2448 to fix it on the Python side, mirroring the approach in #1563:

• Inline local $ref pointers in the tool inputSchema at registration time
• Cache resolved defs (diamond references resolve once)
• Cycles handled gracefully — cyclic $ref left in place with $defs entries preserved (so existing recursive schemas keep working, just degraded rather than expanded)
• Sibling keywords alongside $ref preserved per JSON Schema 2020-12 semantics

Worth landing #1563 + #2448 together for consistent cross-SDK behavior — otherwise downstream MCP clients see different schema shapes depending on whether the server is Python or TypeScript, which makes "supports any MCP server" a false claim for tool-heavy servers.

(Side note: #1175 mentioned in the OP is a slightly different beast — AJV-side validator error rather than LLM-side stringification — but the inline-refs fix here would close it as a downstream consequence.)