Treat content-block, Image and Audio return annotations as unstructured tool output

A tool annotated to return a content block (-> EmbeddedResource, -> TextContent,
-> list[ContentBlock], ...) had the block model's own pydantic schema published as
its output_schema and every block echoed into structured_content a second time,
while Image/Audio inside a generic (-> list[Image], -> Image | Audio) failed to
register at all. -> Image escaped only because Image is a plain class.

In auto-detect mode, an annotation that mentions a content block class or the
Image/Audio helpers anywhere in its type tree now derives no output schema,
matching what _convert_to_content already does with those values at runtime.
structured_output=True still forces a schema. Behaviour change vs v1/2.0, so it
is documented in the migration guide and the structured-output page.

Author: maxisbey

docs/migration.md

@@ -677,7 +677,7 @@ All submodules under `mcp.server.fastmcp.*` are now under `mcp.server.mcpserver.
 Beyond the changes covered in this section, the everyday `FastMCP` surface carries over to `MCPServer` as-is:
 
 - **Decorators.** `@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()`, and `@mcp.completion()` take the same arguments and handler signatures as v1. The lowlevel [`on_completion` reshape](#lowlevel-server-decorator-based-handlers-replaced-with-constructor-on_-params) applies only to the lowlevel `Server`; a high-level `@mcp.completion()` handler is still called as `(ref, argument, context)`.
-- **Tool return handling.** A returned `CallToolResult` (including an `Annotated[CallToolResult, YourModel]` output schema, and `_meta`) is passed through, `Image` and `Audio` convert to content blocks as before, ready-made content blocks are kept as-is, and dict, list, scalar, and model returns are wrapped into `content` and `structured_content` by the same rules.
+- **Tool return handling.** A returned `CallToolResult` (including an `Annotated[CallToolResult, YourModel]` output schema, and `_meta`) is passed through, `Image` and `Audio` convert to content blocks as before, ready-made content blocks are kept as-is (neither is [structured by default](#content-block-image-and-audio-return-annotations-are-unstructured) now, even inside a `list`), and dict, list, scalar, and model returns are wrapped into `content` and `structured_content` by the same rules.
 - **Listing and registration methods.** `list_tools()`, `list_resources()`, `list_resource_templates()`, and `list_prompts()` return the same lists and are still what the protocol handlers call, so subclass overrides still take effect. `add_tool()`, `add_resource()`, and `add_prompt()` are unchanged.
 - **Helpers.** `Image.to_image_content()`, `Audio.to_audio_content()`, and the prompt `Message`, `UserMessage`, and `AssistantMessage` classes.
 - **Lifespan.** The `lifespan=` constructor argument and `ctx.request_context.lifespan_context` work as before, and the class is still generic over the lifespan result: `FastMCP[MyState]` becomes `MCPServer[MyState]`. (`Context`'s own type parameters did change; see [`RequestContext` type parameters simplified](#requestcontext-type-parameters-simplified).)
@@ -924,6 +924,22 @@ running on the event-loop thread:
 
 Declare the handler `async def` to keep it on the event loop.
 
+### Content-block, `Image`, and `Audio` return annotations are unstructured
+
+A tool whose return annotation mentions a content block (`TextContent`,
+`ImageContent`, `AudioContent`, `ResourceLink`, `EmbeddedResource`), `Image`, or
+`Audio` anywhere (alone, or inside a `list`, `tuple`, or union) now registers
+with no `output_schema` and returns no `structured_content`; `content` is built
+exactly as before. v1 (and 2.0) published the block type's own Pydantic schema as
+the tool's `output_schema` and echoed the serialized blocks into
+`structured_content` a second time, while an annotation with `Image` or `Audio`
+inside a generic (`-> list[Image]`) raised at registration (a bare `-> Image` was
+already unstructured).
+
+If a client reads `structured_content` from such a tool, return a model,
+`TypedDict`, or `dict` instead, or pass `structured_output=True` to keep
+publishing a content block's schema.
+
 ### `MCPServer.call_tool()` returns `CallToolResult`
 
 `MCPServer.call_tool()` now returns a `CallToolResult` (or an

docs/servers/structured-output.md

@@ -210,7 +210,7 @@ The opposite, `structured_output=True`, turns the automatic detection into a req
 
 ## A class without type hints
 
-There is one way to end up unstructured without asking for it: return a class that has **no annotations on its body**.
+Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, alone or inside a `list` or union) are not structured automatically: they are for the model to read (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). Beyond those, there is one way to end up unstructured without asking for it: return a class that has **no annotations on its body**.
 
 ```python title="server.py" hl_lines="6-9"
 --8<-- "docs_src/structured_output/tutorial009.py"
@@ -240,6 +240,6 @@ There is one way to end up unstructured without asking for it: return a class th
 * Scalars, lists, tuples and unions are wrapped in `{"result": ...}`. Models, `TypedDict`s, dataclasses, annotated classes and `dict[str, ...]` are objects already and stay as they are.
 * Every result carries `content` (text, for the model) **and** `structured_content` (data, for the application).
 * What you return is validated against the schema. A mismatch is a tool error, not a corrupt result.
-* `structured_output=False` opts a tool out. A class without type hints opts out silently; watch for it.
+* `structured_output=False` opts a tool out. Content blocks, `Image` and `Audio` opt out by default; a class without type hints opts out silently, so watch for it.
 
 You now own everything a tool can say back. Next, the second primitive: **[Resources](resources.md)**.

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

@@ -33,6 +33,16 @@ def _is_input_required_type(obj: Any) -> bool:
     return isinstance(obj, type) and issubclass(obj, InputRequiredResult)
 
 
+_CONTENT_TYPES = (*get_args(ContentBlock), Image, Audio)
+
+
+def _contains_content_type(tp: Any) -> bool:
+    """Whether `tp` is, or is parameterized by, a content block class or the `Image`/`Audio` helpers."""
+    if get_origin(tp) is not None:
+        return any(_contains_content_type(arg) for arg in get_args(tp))
+    return isinstance(tp, type) and issubclass(tp, _CONTENT_TYPES)
+
+
 class StrictJsonSchema(GenerateJsonSchema):
     """A JSON schema generator that raises exceptions instead of emitting warnings.
 
@@ -222,6 +232,9 @@ def func_metadata(
             - TypedDict - converted to a Pydantic model with same fields
             - Dataclasses and other annotated classes - converted to Pydantic models
             - Generic types (list, dict, Union, etc.) - wrapped in a model with a 'result' field
+            - Content blocks (TextContent, EmbeddedResource, ...), Image and Audio, anywhere in the
+                annotation - unstructured when auto-detecting; structured_output=True bypasses this rule
+                (a content block then publishes its own schema; Image/Audio have none and raise)
 
     Returns:
         A FuncMetadata object containing:
@@ -345,6 +358,12 @@ def func_metadata(
     else:
         original_annotation = effective_annotation
 
+    if structured_output is None and _contains_content_type(return_type_expr):
+        # Content blocks and the Image/Audio helpers are what the model reads, not data for the
+        # application: deriving a schema would publish the block's own model as output_schema and
+        # echo every block into structured_content. structured_output=True still forces one.
+        return FuncMetadata(arg_model=arguments_model)
+
     output_model, output_schema, wrap_output = _try_create_model_and_schema(
         original_annotation, return_type_expr, func.__name__
     )

tests/server/mcpserver/test_func_metadata.py

@@ -10,9 +10,10 @@
 import annotated_types
 import pytest
 from dirty_equals import IsPartialDict
-from mcp_types import CallToolResult, InputRequiredResult
+from mcp_types import CallToolResult, ContentBlock, EmbeddedResource, InputRequiredResult, TextContent
 from pydantic import BaseModel, Field
 
+from mcp.server.mcpserver import Audio, Image
 from mcp.server.mcpserver.exceptions import InvalidSignature
 from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 
@@ -854,6 +855,61 @@ def func_returning_unannotated() -> UnannotatedClass:  # pragma: no cover
     assert meta.output_schema is None
 
 
+def _returns_block() -> EmbeddedResource:
+    raise NotImplementedError
+
+
+def _returns_blocks() -> list[ContentBlock]:
+    raise NotImplementedError
+
+
+def _returns_strings_and_images() -> list[str | Image]:
+    raise NotImplementedError
+
+
+def _returns_audio_clips() -> tuple[Audio, ...]:
+    raise NotImplementedError
+
+
+def _returns_call_tool_result_annotated_with_blocks() -> Annotated[CallToolResult, list[TextContent]]:
+    raise NotImplementedError
+
+
+@pytest.mark.parametrize(
+    "tool",
+    [
+        _returns_block,
+        _returns_blocks,
+        _returns_strings_and_images,
+        _returns_audio_clips,
+        _returns_call_tool_result_annotated_with_blocks,
+    ],
+)
+def test_content_block_return_annotation_yields_no_output_schema(tool: Callable[..., Any]):
+    """SDK-defined: content blocks and the Image/Audio helpers anywhere in the return annotation are
+    presentation, not data, so auto-detection derives no output schema (and `list[str | Image]` /
+    `tuple[Audio, ...]`, which pydantic cannot build a schema for, register instead of raising)."""
+    assert func_metadata(tool).output_schema is None
+
+
+def test_structured_output_true_overrides_the_content_block_rule():
+    """SDK-defined: the explicit flag still publishes the block's own schema for callers who want it."""
+    assert func_metadata(_returns_block, structured_output=True).output_model is EmbeddedResource
+
+
+def test_model_with_a_content_block_field_stays_structured():
+    """SDK-defined: only the return annotation is inspected for content types, never a model's fields."""
+
+    class Report(BaseModel):
+        summary: str
+        attachment: EmbeddedResource
+
+    def tool() -> Report:
+        raise NotImplementedError
+
+    assert func_metadata(tool).output_model is Report
+
+
 def test_tool_call_result_is_unstructured_and_not_converted():
     def func_returning_call_tool_result() -> CallToolResult:
         return CallToolResult(content=[])

tests/server/mcpserver/test_server.py

@@ -437,20 +437,8 @@ async def test_tool_mixed_content(self):
             assert isinstance(content3, AudioContent)
             assert content3.mime_type == "audio/wav"
             assert content3.data == "def"
-            assert result.structured_content is not None
-            assert "result" in result.structured_content
-            structured_result = result.structured_content["result"]
-            assert len(structured_result) == 3
-
-            expected_content = [
-                {"type": "text", "text": "Hello"},
-                {"type": "image", "data": "abc", "mimeType": "image/png"},
-                {"type": "audio", "data": "def", "mimeType": "audio/wav"},
-            ]
-
-            for i, expected in enumerate(expected_content):
-                for key, value in expected.items():
-                    assert structured_result[i][key] == value
+            # Content blocks are for the model, not data: no output schema, nothing echoed as structured
+            assert result.structured_content is None
 
     async def test_tool_mixed_list_with_audio_and_image(self, tmp_path: Path):
         """Test that lists containing Image objects and other types are handled
@@ -463,10 +451,8 @@ async def test_tool_mixed_list_with_audio_and_image(self, tmp_path: Path):
         audio_path = tmp_path / "test.wav"
         audio_path.write_bytes(b"test audio data")
 
-        # TODO(Marcelo): It seems if we add the proper type hint, it generates an invalid JSON schema.
-        # We need to fix this.
-        def mixed_list_fn() -> list:  # type: ignore
-            return [  # type: ignore
+        def mixed_list_fn() -> list[str | Image | Audio | dict[str, str] | TextContent]:
+            return [
                 "text message",
                 Image(image_path),
                 Audio(audio_path),
@@ -475,7 +461,7 @@ def mixed_list_fn() -> list:  # type: ignore
             ]
 
         mcp = MCPServer()
-        mcp.add_tool(mixed_list_fn)  # type: ignore
+        mcp.add_tool(mixed_list_fn)
         async with Client(mcp) as client:
             result = await client.call_tool("mixed_list_fn", {})
             assert len(result.content) == 5
@@ -501,7 +487,7 @@ def mixed_list_fn() -> list:  # type: ignore
             content5 = result.content[4]
             assert isinstance(content5, TextContent)
             assert content5.text == "direct content"
-            # Check structured content - untyped list with Image objects should NOT have structured output
+            # Image/Audio/TextContent in the annotation: no output schema, so nothing echoed as structured
             assert result.structured_content is None
 
     async def test_tool_structured_output_basemodel(self):