Add dereference helper for tool inputSchema with nested Pydantic models

[Burton-David]

Problem

When a tool's inputSchema is built from a Pydantic model containing nested BaseModel types, model_json_schema() emits a \$defs block with named definitions and \$ref pointers at each use site. The output is valid JSON Schema 2020-12, but some MCP clients (notably Claude Desktop during the tools/list discovery flow) don't resolve internal \$ref references — tools with nested types in their inputs become invisible or unusable in those clients.

The current workaround that downstream MCP servers reach for is "flatten every input model by hand" — this leaks a Pydantic limitation into the public API surface of every MCP author who hits the issue. In our case (research-mcp, ~14 tools), we hand-flattened all input models.

Proposed shape

A small, additive helper that post-processes the output of model_json_schema():

```python
from mcp.server.mcpserver.utilities.json_schema import dereference_json_schema

flat = dereference_json_schema(MyToolInput.model_json_schema())

`flat` has no $defs; every internal $ref has been inlined.

```

• Pure function. Doesn't mutate the input.
• Only handles internal `#/$defs/` refs. External refs (URLs, pointers into other documents) preserved verbatim.
• Self-referential and mutually recursive definitions are handled safely: `$ref` is preserved at the cycle boundary and the relevant `$defs` entries are retained so the output schema stays valid.
• Sibling keys to `$ref` (allowed by JSON Schema 2020-12; emitted by Pydantic for some types) are merged into the resolved object, with sibling values overriding the resolved definition's values (matches the JSON Schema 2020-12 semantics for sibling annotations).

Default behavior of the SDK is unchanged — this is purely additive. Callers opt in. Existing tools/users who prefer the compact `$ref` form are unaffected.

Why a helper rather than a flag on `model_json_schema`

A flag on `model_json_schema` would have to live in Pydantic. A helper in the SDK is a one-line change at the call site for users who need it, and doesn't require coordinating across projects.

Implementation

I have a working implementation with 21 tests covering: flat schemas, single-level inlining, transitive resolution, arrays, anyOf, sibling key merging, external refs, unknown internal refs, direct self-reference, mutual recursion, and idempotency. All existing `tests/server/mcpserver/test_func_metadata.py` and `test_tool_manager.py` tests still pass (no regressions).

Happy to open a PR once this is `ready for work`.

[jshaofa-ui]

🔧 Root Cause Analysis & Fix Proposal

Problem

When tool inputSchema uses nested BaseModel, Pydantic's model_json_schema() emits $defs + $ref references that MCP clients (Claude Desktop, etc.) cannot resolve, making tools with nested inputs invisible.

Root Cause

Tool.from_function() → model_json_schema() → inputSchema in tools/list response passes the $defs-containing schema directly to clients. MCP clients expect a flat schema without internal $ref pointers.

Suggested Fix

Add a dereference_json_schema() helper that inlines $defs references:

def dereference_json_schema(schema: dict) -> dict:
    """Inline all $defs references into the schema for MCP client compatibility."""
    defs = schema.pop("$defs", {})
    if not defs:
        return schema

    def resolve(obj):
        if isinstance(obj, dict):
            if "$ref" in obj:
                ref = obj["$ref"]
                if ref.startswith("#/$defs/"):
                    name = ref.split("/")[-1]
                    if name in defs:
                        return resolve(defs[name].copy())
            return {k: resolve(v) for k, v in obj.items()}
        elif isinstance(obj, list):
            return [resolve(item) for item in obj]
        return obj

    return resolve(schema)

Files to Change

• src/mcp/server/fastmcp/tools/base.py: Apply dereference before returning inputSchema
• src/mcp/server/fastmcp/server.py: Apply dereference in tools/list handler
• tests/server/test_dereference.py: Add 21 unit tests

Impact

• Severity: High — tools with nested inputs are completely invisible to MCP clients
• Fix complexity: Low — single helper function, ~150 LOC
• Risk: Low — pure schema transformation, no behavior change

[maxisbey]

Closing as a duplicate of #2384 — same $ref/$defs problem and same proposed helper shape; the auto-vs-opt-in question can be settled there. Your implementation notes (especially on cycle handling) would be a great addition to that thread. If this turns out to be a distinct issue, feel free to reopen or open a new one.

_{AI Disclaimer}