Skip to main content

​
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 refreferencesthatpointtoref 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 refwhilepreservingref 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 refresolvedwherepossibleandref 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 refattherootlevelpointingtoref 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.