Icons and presentation metadata in MCP

Icons are optional presentation metadata

Icons let an MCP server supply visual identifiers for objects that a client may show to a person. They decorate tools, resources, resource templates, and prompts; they do not define what those objects can do or how protocol operations behave.

Where icons are permitted

The 2025-11-25 specification changelog records icon support as a change from the 2025-06-18 revision. A server may now attach icons to four kinds of object:

• tools returned through tool discovery;
• resources returned through resource discovery;
• resource templates returned through template discovery;
• prompts returned through prompt discovery.

The field is an optional array named icons, not a single required image. This lets a server offer more than one suitable rendering while allowing clients to ignore the array entirely. For a parameterized resource template, the icon describes the template presented during discovery rather than changing the resource URI produced from that template.

Resources and resource templates are separate schema objects, so each can carry its own icon metadata. A concrete resource may therefore have presentation metadata even when the template from which its URI could be constructed has none, and the reverse is also valid.

What an icon entry contains

The MCP schema reference for Icon defines one required field and three optional hints. src is the required source URI. It points to the icon data and may identify an HTTP or HTTPS resource or carry Base64-encoded image data in a data: URI.

mimeType may supply the media type when the source does not provide a useful one. sizes is an array of supported dimensions, written in forms such as 48x48; scalable artwork may use any. theme may be light or dark, indicating the background for which that icon was designed. When size or theme is absent, the schema tells the client to treat the icon as usable at any size or with either theme.

These fields are hints for selecting and rendering an image. They are not parameters sent when calling a tool, reading a resource, expanding a resource template, or retrieving a prompt. A client can use the hints to choose among entries in the icons array, but it does not have to display an icon to operate the object.

Tool icons do not alter tool calls

The specification’s tool discovery example places icons beside a tool’s name, title, description, schemas, and execution metadata in a tools/list result. The later tools/call request still identifies the tool by name and supplies its arguments; the icon is not part of invocation.

That separation is the governing rule for all four object types: presentation metadata does not change capability semantics. Adding, replacing, or removing an icon must not grant a capability, change an input or output contract, modify a resource URI, alter prompt arguments, or affect whether an operation is available. Those properties remain in their established protocol fields and flows.

Icon presence is consequently not a capability signal. A client should rely on the normal MCP capability negotiation and discovery methods when deciding which operations exist. Inferring support from an image, its URI, or its filename would couple behavior to optional decoration.

Required client fallback

Clients must remain usable when presentation metadata is absent. A server can omit icons from every object and still expose valid tools, resources, resource templates, and prompts. A client that renders icons therefore needs a non-icon presentation, using the object’s ordinary textual and structural metadata rather than leaving an empty control or making the object inaccessible.

The same principle applies when a client elects not to fetch an icon, cannot render it, or has no visual interface. The protocol object remains available through its normal discovery and operation paths. Icon handling may improve recognition in a graphical client, but it cannot be a precondition for use.

For the surrounding mechanics, check how clients discover and read MCP resources and how resource templates turn parameters into resource URIs. Those flows determine what the server exposes and how the client accesses it; icon metadata only affects how discovered entries may be presented.