Skip to content

πŸš€ 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.mdx
index 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.
```python
from fastmcp.utilities.types import Image, Audio, File
@@ -400,24 +401,29 @@ from fastmcp.utilities.types import Image, Audio, File
@mcp.tool
def get_chart() -> Image:
"""Generate a chart image."""
- # From file path - MIME type detected from extension
return 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