diff --git a/docs/specification/draft/basic/index.mdx b/docs/specification/draft/basic/index.mdx index a72073278..750b2056d 100644 --- a/docs/specification/draft/basic/index.mdx +++ b/docs/specification/draft/basic/index.mdx @@ -147,3 +147,54 @@ may reserve particular names for purpose-specific metadata, as declared in those - Unless empty, MUST begin and end with an alphanumeric character (`[a-z0-9A-Z]`). - MAY contain hyphens (`-`), underscores (`_`), dots (`.`), and alphanumerics in between. + +#### `icons` + +The `icons` property provides a standardized way for servers to expose visual identifiers for their resources, tools, prompts, and implementations. Icons enhance user interfaces by providing visual context and improving the discoverability of available functionality. + +Icons are represented as an array of `Icon` objects, where each icon includes: + +- `src`: A URI pointing to the icon resource (required). This can be: + - An HTTP/HTTPS URL pointing to an image file + - A data URI with base64-encoded image data +- `mimeType`: Optional MIME type if the server's type is missing or generic +- `sizes`: Optional size specification (e.g., "48x48", "any" for scalable formats like SVG, or "48x48 96x96" for multiple sizes) + +**Required MIME type support:** + +Clients that support rendering icons **MUST** support at least the following MIME types: + +- `image/png` - PNG images (safe, universal compatibility) +- `image/jpeg` (and `image/jpg`) - JPEG images (safe, universal compatibility) + +Clients that support rendering icons **SHOULD** also support: + +- `image/svg+xml` - SVG images (scalable but requires security precautions as noted below) +- `image/webp` - WebP images (modern, efficient format) + +**Security considerations:** + +Consumers of icon metadata **MUST** take appropriate security precautions when handling icons to prevent compromise: + +- Treat icon metadata and icon bytes as untrusted inputs and defend against network, privacy, and parsing risks. +- Ensure that the icon URI is either a HTTPS or `data:` URI. Clients **MUST** reject icon URIs that use unsafe schemes and redirects, such as `javascript:`, `file:`, `ftp:`, `ws:`, or local app URI schemes. + - Disallow scheme changes and redirects to hosts on different origins. +- Be resilient against resource exhaustion attacks stemming from oversized images, large dimensions, or excessive frames (e.g., in GIFs). + - Consumers **MAY** set limits for image and content size. +- Fetch icons without credentials. Do not send cookies, `Authorization` headers, or client credentials. +- Verify that icon URIs are from the same origin as the server. This minimizes the risk of exposing data or tracking information to third-parties. +- Exercise caution when fetching and rendering icons as the payload **MAY** contain executable content (e.g., SVG with [embedded JavaScript](https://www.w3.org/TR/SVG11/script.html) or [extended capabilities](https://www.w3.org/TR/SVG11/extend.html)). + - Consumers **MAY** choose to disallow specific file types or otherwize sanitize icon files before rendering. +- Validate MIME types and file contents before rendering. Treat the MIME type information as advisory. Detect content type via magic bytes; reject on mismatch or unknown types. + - Maintain a strict allowlist of image types. + +**Usage:** + +Icons can be attached to: + +- `Implementation`: Visual identifier for the MCP server/client implementation +- `Tool`: Visual representation of the tool's functionality +- `Prompt`: Icon to display alongside prompt templates +- `Resource`: Visual indicator for different resource types + +Multiple icons can be provided to support different display contexts and resolutions. Clients should select the most appropriate icon based on their UI requirements. diff --git a/docs/specification/draft/basic/lifecycle.mdx b/docs/specification/draft/basic/lifecycle.mdx index 9f134a6f1..f8a022bab 100644 --- a/docs/specification/draft/basic/lifecycle.mdx +++ b/docs/specification/draft/basic/lifecycle.mdx @@ -69,7 +69,15 @@ The client **MUST** initiate this phase by sending an `initialize` request conta "clientInfo": { "name": "ExampleClient", "title": "Example Client Display Name", - "version": "1.0.0" + "version": "1.0.0", + "icons": [ + { + "src": "https://example.com/icon.png", + "mimeType": "image/png", + "sizes": "48x48" + } + ], + "websiteUrl": "https://example.com" } } } @@ -99,7 +107,15 @@ The server **MUST** respond with its own capabilities and information: "serverInfo": { "name": "ExampleServer", "title": "Example Server Display Name", - "version": "1.0.0" + "version": "1.0.0", + "icons": [ + { + "src": "https://example.com/server-icon.svg", + "mimeType": "image/svg+xml", + "sizes": "any" + } + ], + "websiteUrl": "https://example.com/server" }, "instructions": "Optional instructions for the client" } diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 8571fe6e2..09d8ddf19 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -10,6 +10,7 @@ the previous revision, [2025-06-18](/specification/2025-06-18). ## Major changes 1. Enhance authorization server discovery with support for [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). (PR [#797](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/797)) +2. Allow servers to expose icons as additional metadata for tools, resources and prompts ([SEP-973](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/973)). ## Other schema changes diff --git a/docs/specification/draft/schema.mdx b/docs/specification/draft/schema.mdx index fd6bbb057..1438743a9 100644 --- a/docs/specification/draft/schema.mdx +++ b/docs/specification/draft/schema.mdx @@ -54,16 +54,29 @@ of the LLM and/or the user.

interface Error {
  code: number;
  data?: unknown;
  message: string;
}
code: number

The error type that occurred.

data?: unknown

Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).

message: string

A short description of the error. The message SHOULD be limited to a concise single sentence.

+### `Icon` + +
interface Icon {
  mimeType?: string;
  sizes?: string;
  src: string;
}

A url pointing to an icon URL or a base64-encoded data URI

Clients that support rendering icons MUST support at least the following MIME types:

Clients that support rendering icons SHOULD also support:

mimeType?: string

Optional override if the server's MIME type is missing or generic.

sizes?: string

e.g. "48x48", "any" (for SVG), or "48x48 96x96"

src: string

A standard URI pointing to an icon resource.

Consumers SHOULD takes steps to ensure URLs serving icons are from the +same domain as the client/server or a trusted domain.

Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain +executable JavaScript

+ ### `ImageContent`
interface ImageContent {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  data: string;
  mimeType: string;
  type: "image";
}

An image provided to or from an LLM.

Optional_meta
_meta?: { [key: string]: unknown }

See General fields: _meta for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

data: string

The base64-encoded image data.

mimeType: string

The MIME type of the image. Different providers may support different image types.

### `Implementation` -
interface Implementation {
  name: string;
  title?: string;
  version: string;
}

Describes the name and version of an MCP implementation, with an optional title for UI representation.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +

interface Implementation {
  icons?: Icon[];
  name: string;
  title?: string;
  version: string;
  websiteUrl?: string;
}

Describes the MCP implementation

icons?: Icon[]

An optional list of icons for this implementation. +This can be used by clients to display the implementation in a user interface. +Each icon should have a kind property that specifies whether it is a data representation or a URL source, a src property that points to the icon file or data representation, and may also include a mimeType and sizes property. +The mimeType property should be a valid MIME type for the icon file, such as "image/png" or "image/svg+xml". +The sizes property should be a string that specifies one or more sizes at which the icon file can be used, such as "48x48" or "any" for scalable formats like SVG. +The sizes property is optional, and if not provided, the client should assume that the icon can be used at any size.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, where annotations.title should be given precedence over using name, -if present).

+if present).

websiteUrl?: string

An optional URL of the website for this implementation.

Consumers SHOULD takes steps to ensure URLs serving icons are from the +same domain as the client/server or a trusted domain.

Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain +executable JavaScript

@format: uri

### `JSONRPCError` @@ -123,7 +136,12 @@ without nested objects or arrays.

interface Prompt {
  _meta?: { [key: string]: unknown };
  arguments?: PromptArgument[];
  description?: string;
  name: string;
  title?: string;
}

A prompt or prompt template that the server offers.

Optional_meta
_meta?: { [key: string]: unknown }

See General fields: _meta for notes on _meta usage.

arguments?: PromptArgument[]

A list of arguments to use for templating the prompt.

description?: string

An optional description of what this prompt provides

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +

interface Prompt {
  _meta?: { [key: string]: unknown };
  arguments?: PromptArgument[];
  description?: string;
  icons?: Icon[];
  name: string;
  title?: string;
}

A prompt or prompt template that the server offers.

Optional_meta
_meta?: { [key: string]: unknown }

See General fields: _meta for notes on _meta usage.

arguments?: PromptArgument[]

A list of arguments to use for templating the prompt.

description?: string

An optional description of what this prompt provides

icons?: Icon[]

An optional list of icons for a prompt. +This can be used by clients to display the prompt's icon in a user interface. +Each icon should have a kind property that specifies whether it is a data representation or a URL source, a src property that points to the icon file or data representation, and may also include a mimeType and sizes property. +The mimeType property should be a valid MIME type for the icon file, such as "image/png" or "image/svg+xml". +The sizes property should be a string that specifies one or more sizes at which the icon file can be used, such as "48x48" or "any" for scalable formats like SVG. +The sizes property is optional, and if not provided, the client should assume that the icon can be used at any size.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, where annotations.title should be given precedence over using name, if present).

@@ -153,7 +171,12 @@ if present).