GeezerVison

Backport of #3376 to the v1.x line. Refs #3337.

When a FastMCP tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"} with no type at the root. Tool.outputSchema requires type: "object" at the root on every protocol version v1.x speaks, and strict clients — TypeScript SDK 1.x, C# SDK 1.x, and python-sdk 2.x on a 2025-11-25 session — reject the entire tools/list result when one tool publishes that shape. This inlines the referenced definition onto the root and keeps $defs for the nested references.

Motivation and Context

On v1.x nothing errors on the Python side (Tool.outputSchema is dict[str, Any] and isn't shape-checked), so the failure shows up in the peer: a host embedding the TypeScript SDK 1.x sees the server as having no tools at all. That's the same report as PrefectHQ/fastmcp#2455. Given the blast radius against the most common client family and the size of the change, this seemed worth carrying on the maintenance line.

How Has This Been Tested?

• test_structured_output_self_referential_model_gets_an_object_root pins the generated shape and round-trips a nested result.
• test_tool_structured_output_self_referential_model drives an in-memory client session through tools/list and tools/call; both fail before the change.
• Fed the resulting wire ListToolsResult to the TypeScript SDK 1.x ListToolsResultSchema: accepted after the change, tools.0.outputSchema.type Invalid input: expected "object" before. Also valid against the spec's schema/2025-11-25/schema.json.

Breaking Changes

None. The only observable change is the JSON content of outputSchema for recursive return types: the root gains the definition's keys, $defs is unchanged, structuredContent is unchanged.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Same out-of-scope note as #3376: a RootModel whose root isn't an object still publishes a non-object root.

_{AI Disclaimer}