What is ImageContent?
ImageContent is one of the concrete content-block types in MCP's typed union for tool results and message payloads. It carries a raw image as a base64-encoded string alongside a declared MIME type, giving the host application everything it needs to decode and render the image without any additional round-trips. Structurally it sits alongside TextContent and EmbeddedResource as the third leaf type you will encounter in ToolResult.content arrays, and it can also appear inside sampling request messages where an image is part of the conversation context. The required fields are type (always the literal "image"), data (the base64-encoded bytes), and mimeType (e.g. "image/png", "image/jpeg", "image/gif", "image/webp"). The optional annotations field accepts the shared Annotations object, which lets servers attach audience hints or priority metadata — the same lightweight tagging mechanism shared across all content-block types. There is no built-in width, height, or alt-text field; those concerns are left to the consuming client or to structured text accompanying the image block. ImageContent was present from the earliest published versions of the spec and has not undergone breaking changes, though early SDK releases varied in how strictly they validated the base64 encoding before forwarding payloads. The design intentionally keeps the schema minimal: by embedding bytes directly rather than a URL, servers avoid requiring the client to make an authenticated out-of-band fetch, which simplifies security boundaries in sandboxed tool environments.
When to use
When a tool produces images.
When NOT to use
For large images — consider ResourceLink pointing at a URL.
Notes
Payload size and transport limits
Base64 encoding inflates binary size by roughly 33%, and most MCP transports (stdio, SSE, HTTP) impose their own message-size ceilings. In practice, images over ~1 MB encoded are likely to hit timeouts or rejection in constrained deployments. Prefer down-sampling or compressing images server-side before encoding, and consider returning a file URI via EmbeddedResource when the host supports it.
MIME type validation is not enforced
The spec requires a mimeType string but does not mandate that clients validate it against the actual bytes. A server that sends image/png with JPEG bytes will usually still render correctly in lenient clients, but strict implementations or security-conscious hosts may reject or sandbox mismatched types. Always derive the MIME type from the actual encoder you used, not from the source file's extension.
Annotations are rarely used but worth knowing
The optional annotations field accepts audience (user, assistant) and priority (0.0–1.0) hints inherited from the shared Annotations schema. For image blocks, audience hints can signal whether the image is intended for the end user or for model consumption in a sampling turn — useful when a server returns both a chart image for the user and a compact text summary for continued reasoning.
No alt-text or accessibility field
ImageContent has no dedicated alt-text or caption field. If your tool returns images that need accessible descriptions, the idiomatic pattern is to include a TextContent block in the same content array with a human-readable description. Some SDK wrappers provide helper constructors that bundle the two together, but the spec itself does not couple them.
Comparison with EmbeddedResource
When the image already exists as a named resource on the server, returning it as an EmbeddedResource (with a resource URI pointing to a blob resource) is often preferable to inlining base64 bytes in ImageContent. EmbeddedResource allows caching, URI-based deduplication, and avoids re-encoding on every call. Use ImageContent for dynamically generated, ephemeral visuals like charts, screenshots, or rendered diagrams that have no stable URI identity.
Fields
| Field | Type | Required | Purpose |
|---|---|---|---|
| type | 'image' | yes | Discriminator. |
| data | string | yes | Base64-encoded image bytes. |
| mimeType | string | yes | MIME type (image/png, image/jpeg, etc). |
| annotations | Annotations? | no | Optional annotations. |
Examples
PNG image
{ "type": "image", "data": "iVBORw0KGgo...", "mimeType": "image/png" }Common mistakes
❌ Using a URL as data
✅ data must be base64 bytes — use ResourceLink for URLs.