json_schema

fastmcp.utilities.json_schema

Functions

dereference_refs

dereference_refs(schema: dict[str, Any]) -> dict[str, Any]

Resolve all $ref references in a JSON schema by inlining definitions.

This function resolves $ref references that point to$defs, replacing them with the actual definition content while preserving sibling keywords (like description, default, examples) that Pydantic places alongside $ref.

This is necessary because some MCP clients (e.g., VS Code Copilot) don’t properly handle $ref in tool input schemas.

For self-referencing/circular schemas where full dereferencing is not possible, this function falls back to resolving only the root-level $ref while preserving$defs for nested references.

Only local $ref values (those starting with #) are resolved. Remote URIs (http://, file://, etc.) are stripped before resolution to prevent SSRF / local-file-inclusion attacks when proxying schemas from untrusted servers.

Args:

• schema: JSON schema dict that may contain $ref references

Returns:

• A new schema dict with $ref resolved where possible and$defs removed
• when no longer needed

resolve_root_ref

resolve_root_ref(schema: dict[str, Any]) -> dict[str, Any]

Resolve $ref at root level to meet MCP spec requirements.

MCP specification requires outputSchema to have “type”: “object” at the root level. When Pydantic generates schemas for self-referential models, it uses $ref at the root level pointing to$defs. This function resolves such references by inlining the referenced definition while preserving $defs for nested references.

Args:

• schema: JSON schema dict that may have $ref at root level

Returns:

• A new schema dict with root-level $ref resolved, or the original schema
• if no resolution is needed

compress_schema

compress_schema(schema: dict[str, Any], prune_params: list[str] | None = None, prune_additional_properties: bool = False, prune_titles: bool = False, dereference: bool = False) -> dict[str, Any]

Compress and optimize a JSON schema for MCP compatibility.

Args:

• schema: The schema to compress
• prune_params: List of parameter names to remove from properties
• prune_additional_properties: Whether to remove additionalProperties: false. Defaults to False to maintain MCP client compatibility, as some clients (e.g., Claude) require additionalProperties: false for strict validation.
• prune_titles: Whether to remove title fields from the schema
• dereference: Whether to dereference $ref by inlining definitions. Defaults to False; dereferencing is typically handled by middleware at serve-time instead.