Four small MCPServer/client fixes that remove traps the server docs would otherwise have to explain around. One commit per item so they can be reviewed (or dropped) independently.

Behaviour change to call out in the release notes (item 1): a tool whose return annotation is a content-block type (-> EmbeddedResource, -> list[TextContent], -> tuple[TextContent, ...], -> str | TextContent, ...) or has Image/Audio as its list/tuple items no longer advertises outputSchema and no longer returns structuredContent; its content is unchanged. Pass structured_output=True to keep the old shape.

Motivation and Context

1. Content-block, Image and Audio return annotations are unstructured (func_metadata)

@mcp.tool() def f() -> EmbeddedResource published the pydantic schema of the EmbeddedResource class itself (~2 KB) as the tool's outputSchema and echoed the block into structuredContent a second time. Same for -> ResourceLink, -> TextContent, -> list[ContentBlock], tuple[...], unions. -> Image escaped only because Image is a plain class, and -> list[Image] / -> list[str | Image] / -> Image | Audio didn't register at all (PydanticSchemaGenerationError from create_model, outside the existing try).

In auto-detect mode (structured_output=None), a return annotation that declares content blocks or the Image/Audio helpers — bare, as the items of a list/tuple/Sequence, or as the arms of a union (through Annotated/Optional) — now derives no output schema. That is the annotation-level mirror of what _convert_to_content already does with those values at runtime; mapping values and model fields are data and keep their schema exactly as before. structured_output=True still forces a schema. The check sits right before schema derivation, so there is one rule and one override; Annotated[CallToolResult, list[TextContent]] is covered by the same rule (on main that spelling failed every call unless structured_content was hand-built).

Prompt.from_function and ResourceTemplate.from_function only ever needed the argument model but ran the same auto-detection, so an unschematizable return annotation on a prompt or resource template (-> list[SomePlainClass]) failed registration with a tool structured-output error; they now pass structured_output=False, which also keeps this rule from reaching beyond tools.

2. Prompt messages accept Image / Audio (prompts/base.py)

Tools convert the helpers; UserMessage(Image(...)) was a pydantic validation error (client saw -32603), so you had to write Image(...).to_image_content(). Message.__init__ now does the same conversion str already gets. The dict form ({"role": "user", "content": Image(...)}) works too since validation goes through __init__.

A prompt function may also return bare content the way a tool does — Image(...), a ready-made content block, or a list mixing captions and images — and each item becomes one user message; previously anything that wasn't a str/Message/dict was JSON-dumped (an Image arrived as its repr). That last part is its own commit (Prompt functions may return bare content blocks, Image or Audio) and can be dropped independently; the JSON-dump fallback for other values is untouched, and conversion errors (e.g. an unreadable media file) now reach the existing Error rendering prompt ... handler instead of being re-wrapped as Could not convert prompt result to message: <repr>.

3. Prompt message classes exported from mcp.server.mcpserver (__init__.py)

Message, UserMessage, AssistantMessage are re-exported next to Image/Audio, so the prompt examples import everything from one place. (An earlier revision also let add_prompt() take a function like add_tool(); that was dropped — add_resource()/add_prompt() take built objects today, and changing the imperative registration API deserves its own pass across all three primitives. mcp.add_prompt(Prompt.from_function(fn, ...)) remains the runtime-registration spelling.)

4. Stale TODO in Client.send_roots_list_changed

The comment claimed the server can't handle the notification; the lowlevel Server has on_roots_list_changed and tests/interaction/lowlevel/test_roots.py drives it. (The runtime deprecation warning currently fires once per decorated layer for the Client -> ClientSession delegations and for ctx.info() -> ctx.log() -> send_log_message; that is the same across ~10 call sites and is left for a follow-up rather than special-casing roots here.)

How Has This Been Tested?

• New/updated unit tests: parametrized func_metadata cases (bare block, list[ContentBlock], list[str | Image], tuple[Audio, ...], Annotated[CallToolResult, list[TextContent]]), the structured_output=True override, a model with a content-block field staying structured; Image/Audio in UserMessage/AssistantMessage.
• Review-round pins: dict[str, TextContent] and a model with a block field stay structured; a prompt and a resource template with an unschematizable return annotation register; dict-form prompt message with an Image; bare Image/EmbeddedResource/[str, Image] prompt returns; tests/docs_src/test_structured_output.py proves the new page section.
• The existing test_tool_mixed_content flips to structured_content is None; test_tool_mixed_list_with_audio_and_image gets its real annotation back and loses a TODO plus three type: ignores.
• Exercised a user-style server over a real stdio subprocess before/after: on main the module fails to import (-> list[str | Image]), report/blocks advertise outputSchema, and the image prompt is an internal error; on this branch tools/list shows no outputSchema for the content tools (and still one for structured_output=True and a dict[str, float] control) and the prompt renders text/image/audio.

Breaking Changes

None. No signature, export, or documented behaviour changes; per VERSIONING.md these are bug fixes plus additive API for a minor release, so the migration guide is untouched.

The one observable difference is item 1: tools whose return annotation is a content-block type stop advertising outputSchema and stop returning structuredContent (their content is unchanged). No docs page presented that shape as the intended contract (the media page says such results carry no output schema; the structured-output page enumerates models, TypedDicts, dataclasses, scalars and generics), and -> list[Image] not registering was a plain bug. It does show up in the everything-server's test_image_content / test_audio_content / test_embedded_resource / test_multiple_content_types; the conformance scenarios only assert on content, so they are unaffected. Anyone who wants the old shape passes structured_output=True. docs/servers/structured-output.md gets two sentences so the published page stays accurate.

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

Not done here, noted as follow-ups:

• Deprecated public methods delegating to other deprecated public methods emit MCPDeprecationWarning once per layer (Client.set_logging_level/subscribe_resource/unsubscribe_resource/send_progress_notification/send_roots_list_changed, and Context.debug/info/warning/error -> log -> ServerSession.send_log_message). The clean fix is undecorated private bodies that both public layers call, plus a "one warning per call, attributed to the caller" regression test. (The roots deprecation text cites SEP-2577; the notification's removal at 2026-07-28 is SEP-2575 — same pass.)
• Typing indirections: type X = ... (PEP 695) and NewType return annotations are not unwrapped by the content rule, by the existing InputRequiredResult stripping, or by Annotated[CallToolResult, ...] detection (baseline behaviour, not a regression). One alias-resolution step on the inspected return type feeding all three is the right place.
• _try_create_model_and_schema builds its wrapper models outside the try, so -> list[SomePlainClass] on a tool (and structured_output=True with -> list[Image], or dict[str, Image]) still raises a raw PydanticSchemaGenerationError instead of falling back / raising InvalidSignature.
• Path-backed Image/Audio are read and base64-encoded on the event loop wherever they are converted: Tool.run -> convert_result -> _convert_to_content (since v1), Message.__init__ inside an async prompt function, and now render's bare-content arm. Fix once, in the helpers or inside the existing worker-thread hop, for tools and prompts together.
• Prompt message roles: UserMessage and AssistantMessage both declare role: Literal["user", "assistant"] (as in v1), so a dict-form {"role": "assistant", ...} materialises as UserMessage(role="assistant") — wire output is right, isinstance(msg, AssistantMessage) is not. The validator is now left-to-right so content is converted once. Narrowing each subclass to its own literal and discriminating on role works at runtime but trips pyright strict (reportIncompatibleVariableOverride), so the real fix is a small hierarchy reshape plus a decision on whether UserMessage(x, role="assistant") should keep constructing.

The docs pages that motivated this (media, prompts) are being rewritten separately; the doc edits here are only the ones needed to keep currently published statements true.

AI Disclaimer