how to return images from an mcp server

[JINO-ROHIT]

Question

i understand that i can base64 encode the image and return it using ImageContent type, but there seems to be a limit of the size of the image i can move. what is this limit?

is there a better way to do this?

Additional Context

No response

[maxisbey]

There's currently only one way to return image bytes from a tool in MCP, which is base64 in an ImageContent block, so what you're doing is correct.

On the size limit: neither the MCP spec nor this SDK defines one. ImageContent.data is an unconstrained string in the schema, and the python-sdk's stdio and HTTP transports buffer the full message without a cap. So I'm not sure what limit you're hitting. It could be coming from the host application you're connected to (Claude Desktop, Cursor, VS Code, etc.) or from the model API it forwards images to, rather than from MCP itself.

If you want to avoid inlining large blobs in the tool result, the protocol-level alternative today is to return a ResourceLink pointing at a resource your server exposes, and let the client pull the bytes separately via resources/read. That still ends up as base64 on the wire though, just in a separate request.

Related spec change proposals

• Base64 in JSON RPC will not scale for file content modelcontextprotocol#527 — Base64 in JSON-RPC will not scale for file content (tracking issue)
• SEP-2532: Resource Streaming for Binary Content Delivery modelcontextprotocol#2532 — SEP-2532: Resource Streaming for Binary Content Delivery (resources/stream → raw HTTP download)
• SEP-2631: File Objects and Transfer modelcontextprotocol#2631 — SEP-2631: File Objects and Transfer (FileValue outputs + files/getDownload)
• SEP-2356: File input support for tools and elicitation modelcontextprotocol#2356 — SEP-2356: File input support for tools and elicitation (client→server direction; milestoned for next release)
• Response size limit for MCP responses to prevent context overflow in AI Agents modelcontextprotocol#2210 — Response size limit for MCP responses (closed; left to hosts)

_{AI Disclaimer}

[maxisbey]

Closing this as answered — the comment above covers it: base64 in ImageContent is the only SDK/spec-defined path for returning image bytes from a tool today, neither the spec nor this SDK imposes a size limit, and ResourceLink + resources/read is the protocol-level alternative if you want to avoid inlining large blobs in the tool result. Ongoing work on a better story for binary transfer is being tracked in the spec repo (linked above).

If you're hitting a concrete limit and can pin it down to the python-sdk specifically (rather than the host you're connecting through), feel free to reopen with a repro and we'll take another look.

_{AI Disclaimer}