Dereference $ref in tool schemas for MCP client compatibility

[jlowin]

Some MCP clients (like VS Code Copilot) don't properly handle $ref in tool input schemas. When Pydantic generates schemas for Enum types, it uses $defs with $ref pointers:

{
  "$defs": {"Category": {"enum": ["food", "transport"], "type": "string"}},
  "properties": {"category": {"$ref": "#/$defs/Category"}}
}

VS Code Copilot appears to strip $defs before sending to Claude, leaving dangling $ref pointers that cause tool calls to fail.

This PR dereferences all $ref entries in compress_schema() using jsonref, producing clean inlined schemas:

{
  "properties": {"category": {"enum": ["food", "transport"], "type": "string"}}
}

Self-referencing schemas (which can't be fully dereferenced) fall back to resolve_root_ref() for MCP spec compliance.

Background

We previously closed PRs #1192 and #1641 which proposed similar solutions. Our position was that FastMCP's obligation is MCP spec compliance, not working around individual client bugs. However, this issue has persisted for a long time across multiple popular clients (Claude Desktop, VS Code Copilot) that are otherwise excellent. The tradeoff is minimal—slightly larger schemas due to inlining—with no functional compromise. Given how widespread and long-standing this is, it feels reasonable to make this accommodation.

Closes #2807, closes #1193, fixes #2236

[coderabbitai]

Walkthrough

This pull request refactors schema dereferencing by introducing a new dereference_refs() function that inlines $ref values using jsonref.replace_refs and removes $defs sections when fully dereferenced. The compress_schema() function now calls dereference_refs() at the start to ensure MCP compatibility. The prune_defs parameter is removed from compress_schema() signature. Separate resolve_root_ref calls in tool.py are removed since dereferencing is now centralized in compress_schema(). All compress_schema() calls in tool_transform.py are updated to remove the prune_defs argument.

Possibly related PRs

• Fix: resolve root-level $ref in outputSchema for MCP spec compliance #2720: Modifies src/fastmcp/utilities/json_schema.py and src/fastmcp/tools/tool.py with conflicting approaches to root $ref resolution—previous approach added post-compress resolve_root_ref, this approach internalizes dereferencing within compress_schema.

• fix: prevent $defs mutation in Tool.from_tool transforms #2493: Updates compress_schema() calls in src/fastmcp/tools/tool_transform.py to prevent in-place $defs mutation, directly related to changes in this PR's removal of prune_defs argument usage.

• Fix: resolve root-level $ref in outputSchema for MCP spec compliance #2727: Addresses root $ref resolution in the tool.from_function output\_schema flow by adding resolve_root_ref calls, contrasting with this PR's approach of centralizing resolution logic within compress_schema().

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: dereferencing $ref entries in tool schemas for MCP client compatibility, which is the core objective of this PR.
Linked Issues check	✅ Passed	The changes directly address both linked issues: #2807 (Opus rejecting $ref in input schemas) and #1193 (Claude Desktop sending null for enum refs). The PR dereferences $ref entries to produce inlined schemas compatible with stricter MCP clients.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to dereferencing $ref in tool schemas. Modifications to tool.py, tool_transform.py, and json_schema.py are focused on the schema dereferencing workflow with no unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description provides a clear and comprehensive overview of the changes, including problem statement, solution, and context.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 81e2bd8365

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Restrict dereferencing to local $defs

dereference_refs() calls replace_refs(schema, proxies=False, lazy_load=False) without filtering for local #/$defs references. jsonref resolves external URIs eagerly when lazy_load=False, so any schema that includes an external $ref (valid in JSON Schema and possible in user‑supplied tool/input schemas) will now trigger network fetches or raise resolution errors during schema compression. Previously those refs were left intact, so this is a regression that can break tool creation or hang in offline environments. Consider limiting dereferencing to local refs or providing a loader that rejects non‑local refs and leaves them untouched.

Useful? React with 👍 / 👎.