Image/ImageContent serialization fails in stateless HTTP mode

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

Description

When using FastMCP with stateless_http=True (required by Claude.ai remote MCP), returning Image or ImageContent from a @mcp.tool() function results in serialization errors. Text-only tool results work fine in the same configuration.

Environment

• mcp version: 1.26.0 (also tested with >=1.8.0 unpinned)
• Python: 3.12
• Transport: streamable-http
• Deployment: Railway (remote, accessed by Claude.ai)
• Client: Claude.ai (requires stateless_http=True)

Reproduction

Minimal server:

from mcp.server.fastmcp import FastMCP, Image

mcp = FastMCP(
    "test",
    host="0.0.0.0",
    port=8000,
    stateless_http=True,
    json_response=True,
)

@mcp.tool()
def text_tool() -> str:
    """Works fine"""
    return "hello"

@mcp.tool()
def image_tool() -> Image:
    """Fails with serialization error"""
    # 1x1 red PNG
    data = bytes.fromhex(
        "89504e470d0a1a0a0000000d49484452000000010000000108020000009001"
        "2e00000000c4948444154789c6260f8cf00000000020001e221bc330000000049454e44ae426082"
    )
    return Image(data=data, format="png")

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

What happens

Attempt 1: Image class + stateless_http=True + json_response=True

Unable to serialize unknown type: <class 'mcp.server.fastmcp.utilities.types.Image'>

Attempt 2: Image class + stateless_http=True + json_response=False

Same serialization error.

Attempt 3: ImageContent from mcp.types + stateless_http=True

{"error": "Error occurred during tool execution"}

Server returns 200 OK but client receives generic error.

Attempt 4: Image class + stateless_http=False (stateful mode)

POST /mcp HTTP/1.1" 400 Bad Request

Claude.ai rejects stateful mode entirely.

Expected behavior

Image and ImageContent should serialize correctly in stateless_http=True mode, since:

1. The MCP spec defines ImageContent as a valid tool result content type
2. ToolResultContent.content accepts ContentBlock lists which include image content
3. The official SDK docs show @mcp.tool() returning Image as a supported pattern
4. The protocol's Streamable HTTP transport has no text-only restriction — it returns either application/json or text/event-stream, both capable of carrying base64-encoded image data

Context

This blocks any MCP server deployed for Claude.ai from returning images via tool results. The only workaround is returning image URLs as text, which doesn't work for authenticated/signed URLs (e.g., Notion S3 hosted images that require download proxying).

Related

• Python SDK Image example: https://github.com/modelcontextprotocol/python-sdk#primitives
• MCP spec tool results: https://spec.modelcontextprotocol.io/specification/server/tools/

Example Code

Python & MCP Python SDK

MCP version: 1.26.0
Python: 3.12

先使用无状态 HTTP 和 Image 结果开始最小化的 FastMCP 复现，然后跟踪 streamable-HTTP 传输的工具结果序列化路径。将其与正常工作的纯文本结果以及 ImageContent 尝试进行比较。当 Image 和 ImageContent 工具结果在无状态模式下能够携带 base64 图像数据成功返回时，即视为完成。