feat: Add structured output support for tool functions #993

bhosmer-ant · 2025-06-20T15:24:56Z

Adds support for structured output in FastMCP and Client, allowing tool functions to return well-typed, validated data that clients can easily process and validate.

Key Changes

FastMCP:
Adds structured tool support to FastMCP's @mcp.tool() decorator. By default, functions with structured-output-compatible return types become structured tools, other functions become unstructured tools. This behavior can be overridden by passing structured_output=False to the decorator. (structured_output=True will force FastMCP to attempt to create a structured tool, which may be useful in certain edge cases.)

To convert a function into a structured tool,

the function return type annotation is converted into Pydantic model (see "Supported return types" below)
the tool's outputSchema is generated from this model
structuredContent results are validated on the server before sending, via the lowlevel server's structured output support

Client: adds validation of structuredContent results against tool outputSchema
Tests: lots
Docs: added to README.md
Examples: added examples/fastmcp/weather_structured.py showing various return type options

Supported return types

@mcp.tool() supports the following function return types for structured output:

Pydantic models: Used directly to validate function results and generate outputSchema
dict[str, *], TypedDict, NamedTuple, classes with typed fields: Converted to Pydantic models
Primitives, lists, generics: Wrapped in {\"result\": value}

Note on backward compatibility

In keeping with the MCP specification regarding backward compatibility, structured tools will provide both structured results and backwards-compatible unstructured results. In order to provide backward compatibility with previous versions of FastMCP in particular, we do not use the generic JSON serialization provided by the lowlevel server for this purpose. Instead we use the existing FastMCP unstructured results pipeline, which performs several ad hoc conversions of function results. Future versions of FastMCP will instead use the generic lowlevel server pipeline.

Motivation and Context

Support structured output as defined in spec rev 2025-06-18

How Has This Been Tested?

New tests added

Breaking Changes

Protocol defines structured output in a backwards-compatible way
SDK API changes should be backwards compatible

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

Many thanks to @davemssavage, who prototyped an initial version of this functionality.

Kludex · 2025-06-21T14:54:38Z

I don't think the structured_output is needed on the FastMCP. Is it?

ihrpr · 2025-06-23T09:58:14Z

I don't think the structured_output is needed on the FastMCP. Is it?

@Kludex, Structured output is part of the spec. Since FastMCP in this repository serves as a high-level API and is the primary entry point for users to define tools, it needs to include structured_output. This gives users the ability to define tools with structured output support, which is a standard feature of the MCP protocol.

or you mean there is no much need of of the param itself as it's already part of the spec?

Kludex · 2025-06-23T10:08:40Z

Sorry, I meant "does the flag need to exist? Can the behavior be always true and based on the type hints?"

ihrpr

I think we might just use HighLevel API (FastMCP) to always return structured and unstructured output. Given that it always has a return type we can return structured output and unstructured will be non-wrapped output behaviour.
I think it would make sense to have validation on the lowlevel, what is the reason of not having the validation there?

ihrpr · 2025-06-23T10:08:39Z

src/mcp/server/fastmcp/server.py

@@ -315,6 +311,7 @@ def add_tool(
        title: str | None = None,
        description: str | None = None,
        annotations: ToolAnnotations | None = None,
+        structured_output: bool = False,


Is there a reason we want to have a default set to True, given the backwards compatibility, where we also send an unstructured output.

As per other comments, we might just remove this entirely, it will be a nice way to migrate most of the tool to return structure output.

Suggested change

structured_output: bool = False,

structured_output: bool = True,

BC problem with this is that existing tools don't (or may not) map cleanly to structured output - and even when they do, we would need to decide for a given tool whether to employ

the "new structured tool BC conversion" (serializing the json to text and stuffing it into a single TextContent block) or

the "old unstructured tool BC conversion" (running the return value through the old conversion, which leaves content blocks in place and does a few other fairly ad hoc things)

...so defaulting structured_output=True would produce silent breaking changes for a certain class of tools, which seems bad. if there's a way to tighten the valid-structured-return-type rule so that only tools for which the conversion produces the same result make it through without error (and others produce a "please add structured_output=False to your decorator error" message), then we could dodge the silent-BC-break issue, will look into that

ihrpr · 2025-06-23T10:23:05Z

src/mcp/server/fastmcp/utilities/func_metadata.py

@@ -68,6 +84,28 @@ async def call_fn_with_arg_validation(
            return fn(**arguments_parsed_dict)
        raise TypeError("fn must be either Callable or Awaitable")

+    def to_validated_dict(self, result: Any) -> dict[str, Any]:
+        """Validate and convert the result to a dict after validation."""
+        if self.output_model is None:


this was already checked before calling to_validated_dict

true in the current codepath, but it's (currently) a public method

ihrpr · 2025-06-23T10:43:27Z

tests/server/fastmcp/test_server.py

+            assert result.isError is False
+            assert result.structuredContent == {"theme": "dark", "language": "en", "timezone": "UTC"}
+
+    @pytest.mark.anyio


here tests started using lowlevel server

[edit] ah misunderstood your comment - will move lowlevel server tests outta here :)

ihrpr · 2025-06-23T14:05:02Z

src/mcp/server/lowlevel/server.py

+                        json_content = pydantic_core.to_json(results, fallback=str, indent=2).decode()
+                        return types.ServerResult(
+                            types.CallToolResult(
+                                content=[types.TextContent(type="text", text=json_content)],


this will not be fully backwards compatible, would leaving this as content=list(results) work?

the dict return type from a tool is new, so this codepath should be new (for any code that typechecked). Don't think list(results) would work since that would give you [<some python dict>] rather than [TextContent(<serialized python dict>)].

bhosmer-ant · 2025-06-23T14:42:11Z

@ihrpr per offline convo, recapping here

I think we might just use HighLevel API (FastMCP) to always return structured and unstructured output. Given that it always has a return type we can return structured output and unstructured will be non-wrapped output behaviour.

Problems with this are:

not all return types yield a structured output schema (e.g. classes without annotated properties) - if we wanted to define FastMCP as supporting only tools that do, we could do that, but it would be a pretty big (BC breaking) change
BC in general - tools might be returning results that aren't easily represented as structured output, irrespective of return type annotations
new tools might want to return results that aren't easily represented as structured output. (this is more of a "what tools do you want FastMCP to support" design question)

I think it would make sense to have validation on the lowlevel, what is the reason of not having the validation there?

lowlevel doesn't do input validation, so I went with what seemed to be the intent there. But per discussion, it sounds like lowlevel is more heavily used than I realized - will add (output) schema validation there

bhosmer-ant · 2025-06-23T14:46:43Z

Sorry, I meant "does the flag need to exist? Can the behavior be always true and based on the type hints?"

@Kludex see my reply to @ihrpr - making it always true would make some functions ineligible as tools, and would silently change the results returned by others (the latter also an issue with making it default-true)

Kludex · 2025-06-23T15:07:27Z

On the FastMCP repository, they have an analogous PR that seems to not include any parameter: jlowin/fastmcp#901 cc @jlowin

jlowin · 2025-06-23T15:48:19Z

Hey! Just to clarify, jlowin/fastmcp#901 implements output schemas but not structured content (yet) because I'm actually waiting for this low-level PR to be merged so I can fully test those outputs.

That said, the approach we are taking toward structured content in FastMCP 2 is much more opinionated - if a function has a serializable return annotation, it automatically gets structured output, no flags needed. This feels more aligned with what users expect from a high-level SDK (automatic behavior based on type hints) vs low-level SDK (explicit configuration).

That said, I understand the backwards compatibility concerns that motivate the structured_output=True flag approach. Different design philosophies for different use cases!

Happy to share more thoughts on our implementation if it would be helpful. The automatic dict→structured content conversion is definitely a tricky area where user expectations can and will vary.

bhosmer-ant · 2025-06-25T06:17:54Z

Updates:

made structured_output decorator param optional. If not passed, uses type sniffing to decide whether the tool should be structured or unstructured. (Can override by passing the flag explicitly to force either structured or unstructured.)
rebased onto lowlevel server schema validation, although it turns out the multiple ad hoc things FastMCP does to both incoming arguments and results mean we have to jump through some hoops to preserve compatibility. Later versions of FastMCP should break compatibility and simplify.

ihrpr

LGTM, a few things to clean up before merging

README.md

src/mcp/server/fastmcp/utilities/func_metadata.py

The base branch was changed.

- Add support for tool functions to return structured data with validation - Functions can now use structured_output=True to enable output validation - Add outputSchema field to Tool type in MCP protocol - Implement client-side validation of structured content - Add comprehensive tests for all supported types - Add documentation and examples

ihrpr

LGTM

(as discussed, there is potential refactoring opportunity, we can try it out and if not worth it, we can merge)

- strict serializability checking - simpler, more consistent handling of return type detection and conversion - centralized logic

ihrpr

Thank you!

bhosmer-ant requested review from ihrpr and dsp-ant June 20, 2025 15:25

jlowin mentioned this pull request Jun 20, 2025

MCP 6/18/25: Add output schema to tools jlowin/fastmcp#901

Merged

ihrpr requested changes Jun 23, 2025

View reviewed changes

ihrpr reviewed Jun 23, 2025

View reviewed changes

bhosmer-ant force-pushed the basil/structured_output branch 3 times, most recently from ff01365 to 0695b4b Compare June 25, 2025 05:54

bhosmer-ant requested a review from ihrpr June 25, 2025 06:14

ihrpr changed the base branch from main to basil/lowlevel_schema_validation June 25, 2025 07:32

ihrpr previously approved these changes Jun 25, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

src/mcp/server/fastmcp/utilities/func_metadata.py Outdated Show resolved Hide resolved

ihrpr reviewed Jun 25, 2025

View reviewed changes

src/mcp/server/fastmcp/utilities/func_metadata.py Outdated Show resolved Hide resolved

Base automatically changed from basil/lowlevel_schema_validation to main June 25, 2025 13:23

bhosmer-ant added 2 commits June 25, 2025 09:34

rebase on lowlevel schema validation, address comments

98c5ae9

bhosmer-ant force-pushed the basil/structured_output branch 2 times, most recently from 791f6da to 38a2691 Compare June 25, 2025 17:43

ihrpr previously approved these changes Jun 25, 2025

View reviewed changes

move _convert_to_content

3ab59c5

bhosmer-ant dismissed ihrpr’s stale review via 3ab59c5 June 25, 2025 17:46

bhosmer-ant force-pushed the basil/structured_output branch from 38a2691 to 3ab59c5 Compare June 25, 2025 17:46

ihrpr previously approved these changes Jun 25, 2025

View reviewed changes

refactor:

f302a99

- strict serializability checking - simpler, more consistent handling of return type detection and conversion - centralized logic

bhosmer-ant dismissed ihrpr’s stale review via f302a99 June 26, 2025 07:26

ihrpr approved these changes Jun 26, 2025

View reviewed changes

ihrpr merged commit 43bb24f into main Jun 26, 2025
12 checks passed

ihrpr deleted the basil/structured_output branch June 26, 2025 08:36

ihrpr linked an issue Jun 26, 2025 that may be closed by this pull request

add Tool.outputSchema and CallToolResult.structuredContent #919

Closed

davemssavage mentioned this pull request Jun 27, 2025

add Tool.outputSchema and CallToolResult.structuredContent #685

Closed

9 tasks

	structured_output: bool = False,
	structured_output: bool = True,

feat: Add structured output support for tool functions #993

feat: Add structured output support for tool functions #993

Conversation

bhosmer-ant commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Supported return types

Note on backward compatibility

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Kludex commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ihrpr commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex commented Jun 23, 2025

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhosmer-ant commented Jun 23, 2025

Uh oh!

Kludex commented Jun 23, 2025

Uh oh!

jlowin commented Jun 23, 2025

Uh oh!

bhosmer-ant commented Jun 25, 2025

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bhosmer-ant commented Jun 20, 2025 •

edited

Loading

Kludex commented Jun 21, 2025 •

edited

Loading

ihrpr commented Jun 23, 2025 •

edited

Loading

bhosmer-ant Jun 23, 2025 •

edited

Loading

bhosmer-ant commented Jun 23, 2025 •

edited

Loading