π The fast, Pythonic way to build MCP servers and clients.
Document container limitations for Image/Audio/File objects (#2118)
Jeremiah Lowin2f841c356e45
diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdxindex c9e73cfb8..380fe5a7f 100644--- a/docs/servers/tools.mdx+++ b/docs/servers/tools.mdx@@ -387,12 +387,13 @@ FastMCP automatically converts tool return values into appropriate MCP content b- **`fastmcp.utilities.types.Image`**: Sent as `ImageContent`- **`fastmcp.utilities.types.Audio`**: Sent as `AudioContent`- **`fastmcp.utilities.types.File`**: Sent as base64-encoded `EmbeddedResource`-- **A list of any of the above**: Converts each item appropriately+- **MCP SDK content blocks**: Sent as-is+- **A list of any of the above**: Converts each item according to the above rules- **`None`**: Results in an empty response#### Media Helper Classes-For returning images, audio, and files, FastMCP provides helper classes that handle MIME type detection and base64 encoding automatically, returning them in MCP-native formats that meet the protocol's requirements:+FastMCP provides helper classes for returning images, audio, and files. When you return one of these classes, either directly or as part of a list, FastMCP automatically converts it to the appropriate MCP content block. For example, if you return a `fastmcp.utilities.types.Image` object, FastMCP will convert it to an MCP `ImageContent` block with the correct MIME type and base64 encoding.```pythonfrom fastmcp.utilities.types import Image, Audio, File@@ -400,24 +401,29 @@ from fastmcp.utilities.types import Image, Audio, File@mcp.tooldef get_chart() -> Image:"""Generate a chart image."""- # From file path - MIME type detected from extensionreturn Image(path="chart.png")- # Or from raw bytes with explicit format- # return Image(data=image_bytes, format="png")-@mcp.tool-def get_recording() -> Audio:- """Get an audio recording."""- return Audio(path="recording.wav")- # Or: Audio(data=audio_bytes, format="wav")+def get_multiple_charts() -> list[Image]:+ """Return multiple charts."""+ return [Image(path="chart1.png"), Image(path="chart2.png")]+```-def get_document() -> File:- """Retrieve a PDF document."""- return File(path="report.pdf")- # Or: File(data=pdf_bytes, format="pdf", name="report")+<Tip>+Helper classes are only automatically converted to MCP content blocks when returned **directly** or as part of a **list**. For more complex containers like dicts, you can manually convert them to MCP types:++```python+# β Automatic conversion+return Image(path="chart.png")+return [Image(path="chart1.png"), "text content"]++# β Will not be automatically converted+return {"image": Image(path="chart.png")}++# β Manual conversion for nested use+return {"image": Image(path="chart.png").to_image_content()}```+</Tip>Each helper class accepts either `path=` or `data=` (mutually exclusive):- **`path`**: File path (string or Path object) - MIME type detected from extension