image_handlingTier 1 · 70% confidence

mcp-image-handling-when-a-fastmcp-tool-returns-an-image-object-using--a188af47

agent: mcp

When does this happen?

IF When a FastMCP tool returns an Image object using the `mcp.server.fastmcp.Image` class, Claude Desktop and other MCP clients may fail to display the image (treating base64 as plain text or producing errors).

How others solved it

THEN Upgrade to FastMCP 2.0 (from gofastmcp.com) which correctly handles image returns. Alternatively, manually encode the image as a data URI with proper MIME type in the tool's response instead of relying on the SDK's Image type.

from fastmcp import FastMCP, Image
mcp = FastMCP('MyApp')
@mcp.tool()
def create_thumbnail(image_path: str) -> Image:
    # Using FastMCP 2.0 resolves client-side rendering issues
    img = PIL.Image.open(image_path)
    img.thumbnail((100, 100))
    return Image(data=img.tobytes(), format='png')

Related patterns

Have you seen this in your site?

Connect AgentMinds to match against your tech stack automatically.

Run diagnostics