Title: Image/ImageContent serialization fails in stateless HTTP mode · Issue #2376 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: Image/ImageContent serialization fails in stateless HTTP mode · Issue #2376 · modelcontextprotocol/python-sdk
X Title: Image/ImageContent serialization fails in stateless HTTP mode · Issue #2376 · modelcontextprotocol/python-sdk
Description: 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...
Open Graph Description: 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 ...
X Description: 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 t...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/2376
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Image/ImageContent serialization fails in stateless HTTP mode","articleBody":"### Initial Checks\n\n- [x] I confirm that I'm using the latest version of MCP Python SDK\n- [x] I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue\n\n### Description\n\n## Description\n\nWhen 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.\n\n## Environment\n\n- `mcp` version: 1.26.0 (also tested with `>=1.8.0` unpinned)\n- Python: 3.12\n- Transport: `streamable-http`\n- Deployment: Railway (remote, accessed by Claude.ai)\n- Client: Claude.ai (requires `stateless_http=True`)\n\n## Reproduction\n\nMinimal server:\n\n```python\nfrom mcp.server.fastmcp import FastMCP, Image\n\nmcp = FastMCP(\n \"test\",\n host=\"0.0.0.0\",\n port=8000,\n stateless_http=True,\n json_response=True,\n)\n\n@mcp.tool()\ndef text_tool() -> str:\n \"\"\"Works fine\"\"\"\n return \"hello\"\n\n@mcp.tool()\ndef image_tool() -> Image:\n \"\"\"Fails with serialization error\"\"\"\n # 1x1 red PNG\n data = bytes.fromhex(\n \"89504e470d0a1a0a0000000d49484452000000010000000108020000009001\"\n \"2e00000000c4948444154789c6260f8cf00000000020001e221bc330000000049454e44ae426082\"\n )\n return Image(data=data, format=\"png\")\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"streamable-http\")\n```\n\n## What happens\n\n### Attempt 1: `Image` class + `stateless_http=True` + `json_response=True`\n\n```\nUnable to serialize unknown type: \u003cclass 'mcp.server.fastmcp.utilities.types.Image'>\n```\n\n### Attempt 2: `Image` class + `stateless_http=True` + `json_response=False`\n\nSame serialization error.\n\n### Attempt 3: `ImageContent` from `mcp.types` + `stateless_http=True`\n\n```\n{\"error\": \"Error occurred during tool execution\"}\n```\n\nServer returns 200 OK but client receives generic error.\n\n### Attempt 4: `Image` class + `stateless_http=False` (stateful mode)\n\n```\nPOST /mcp HTTP/1.1\" 400 Bad Request\n```\n\nClaude.ai rejects stateful mode entirely.\n\n## Expected behavior\n\n`Image` and `ImageContent` should serialize correctly in `stateless_http=True` mode, since:\n\n1. The MCP spec defines `ImageContent` as a valid tool result content type\n2. `ToolResultContent.content` accepts `ContentBlock` lists which include image content\n3. The official SDK docs show `@mcp.tool()` returning `Image` as a supported pattern\n4. 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\n\n## Context\n\nThis 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).\n\n## Related\n\n- Python SDK Image example: https://github.com/modelcontextprotocol/python-sdk#primitives\n- MCP spec tool results: https://spec.modelcontextprotocol.io/specification/server/tools/\n\n### Example Code\n\n```Python\n\n```\n\n### Python & MCP Python SDK\n\n```Text\nMCP version: 1.26.0\nPython: 3.12\n```","author":{"url":"https://github.com/Kunyu-Chen","@type":"Person","name":"Kunyu-Chen"},"datePublished":"2026-03-29T12:32:53Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/2376"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d8db44b8-902b-c187-d135-303ce0d2e078 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B5FE:3A4875:987DB3:CC80AC:6B00E88F |
| html-safe-nonce | 6da661343565918c9df82b9ae15ba12adbace3a4f1b02b722f0d6edb0eeda18e |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCNUZFOjNBNDg3NTo5ODdEQjM6Q0M4MEFDOjZCMDBFODhGIiwidmlzaXRvcl9pZCI6IjQ3NjIyMzU0NDcyNjQ5OTU0NzEiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | b6bacc2621d54b6c632fd22787a6dc8b060395ce3926c85f44fd45a9a2294b90 |
| hovercard-subject-tag | issue:4164092804 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/2376/issue_layout |
| twitter:image | https://opengraph.githubassets.com/88c277d3b17b767fc7afca6361a78358960bfbb0051cacb739124678cbb1531d/modelcontextprotocol/python-sdk/issues/2376 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/88c277d3b17b767fc7afca6361a78358960bfbb0051cacb739124678cbb1531d/modelcontextprotocol/python-sdk/issues/2376 |
| og:image:alt | 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 ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Kunyu-Chen |
| hostname | github.com |
| expected-hostname | github.com |
| None | 27088b6977484d0d3321d9a11c907c6d6637b315cfa359ef7952dbf6292f9b14 |
| turbo-cache-control | no-preview |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 624179fb8b88d26ba5bba08894eb60a1c5a1d93d |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width