ext-apps/specification/draft/apps.mdx

# SEP-1865: MCP Apps: Interactive User Interfaces for MCP

**Track:** Extensions
**Authors:** Ido Salomon, Liad Yosef, Olivier Chafik, Jerome Swannack, Jonathan Hefner, Anton Pidkuiko, Nick Cooper, Bryan Ashley, Alexei Christakis
**Status:** Draft
**Created:** 2025-11-21

## Abstract

This SEP proposes an extension (per SEP-1724) to MCP that enables servers to deliver interactive user interfaces to hosts. MCP Apps introduces a standardized pattern for declaring UI resources via the `ui://` URI scheme, associating them with tools through metadata, and facilitating bidirectional communication between the UI and the host using MCP's JSON-RPC base protocol. This extension addresses the growing community need for rich, interactive experiences in MCP-enabled applications, maintaining security, auditability, and alignment with MCP's core architecture. The initial specification focuses on HTML resources (`text/html;profile=mcp-app`) with a clear path for future extensions.

## Motivation

MCP lacks a standardized way for servers to deliver rich, interactive user interfaces to hosts. This gap blocks many use cases that require visual presentation and interactivity that goes beyond plain text or structured data. As more hosts adopt this capability, there's a growing risk of fragmentation and interoperability challenges.

[MCP-UI](https://mcpui.dev/) has demonstrated the viability and value of MCP apps built on UI resources and serves as a community playground for the UI spec and SDK. Fuelled by a dedicated community, it developed the bi-directional communication model and the HTML, external URL, and remote DOM content types. MCP-UI's adopters, including hosts and providers such as Postman, HuggingFace, Shopify, Goose, and ElevenLabs, have provided critical insights and contributions to the community.

OpenAI's Apps SDK, launched in November 2025, further validated the demand for rich UI experiences within conversational AI interfaces. The Apps SDK enables developers to build rich, interactive applications inside ChatGPT using MCP as its backbone.

The architecture of both the Apps SDK and MCP-UI have both significantly informed the design of this specification.

However, without formal standardization:

- Servers cannot reliably expect UI support via MCP
- Each host may implement slightly different behaviors
- Security and auditability patterns are inconsistent
- Developers must maintain separate implementations or adapters for different hosts (e.g., MCP-UI vs. Apps SDK)

This SEP addresses the current limitations through an optional, backwards-compatible extension that unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.

## Specification

### Extension Identifier

This extension is identified as: `io.modelcontextprotocol/ui`

### Overview

MCP Apps extends the Model Context Protocol to enable servers to deliver interactive user interfaces to hosts. This extension introduces:

- **UI Resources:** Predeclared resources using the `ui://` URI scheme
- **Tool-UI Linkage:** Tools reference UI resources via metadata
- **Bidirectional Communication:** UI iframes communicate with hosts using standard MCP JSON-RPC protocol
- **Security Model:** Mandatory iframe sandboxing with auditable communication

This specification focuses on HTML content (`text/html;profile=mcp-app`) as the initial content type, with extensibility for future formats.

As an extension, MCP Apps is optional and must be explicitly negotiated between clients and servers through the extension capabilities mechanism (see Capability Negotiation section).

### UI Resource Format

UI resources are declared using the standard MCP resource pattern with specific conventions:

```typescript
interface UIResource {
  /**
   * Unique identifier for the UI resource
   *
   * MUST use the `ui://` URI scheme to distinguish UI resources from other
   * MCP resource types.
   *
   * @example
   * "ui://weather-dashboard"
   */
  uri: string;

  /**
   * Human-readable display name for the UI resource
   *
   * Used for listing and identifying the resource in host interfaces.
   *
   * @example
   * "Weather Dashboard"
   */
  name: string;

  /**
   * Optional description of the UI resource's purpose and functionality
   *
   * Provides context about what the UI does and when to use it.
   *
   * @example
   * "Interactive weather visualization with real-time updates"
   */
  description?: string;

  /**
   * MIME type of the UI content
   *
   * SHOULD be `text/html;profile=mcp-app` for HTML-based UIs in the initial MVP.
   * Other content types are reserved for future extensions.
   *
   * @example
   * "text/html;profile=mcp-app"
   */
  mimeType: string;

  /**
   * Resource metadata for security and rendering configuration
   *
   * Includes Content Security Policy configuration, dedicated domain settings,
   * and visual preferences.
   */
  _meta?: {
    ui?: UIResourceMeta;
  }
}

interface UIResourceMeta {
  /**
   * Content Security Policy configuration
   *
   * Servers declare which external origins their UI needs to access.
   * Hosts use this to enforce appropriate CSP headers.
   */
  csp?: {
    /**
     * Origins for network requests
     *
     * - Empty or omitted = no external connections (secure default)
     * - Maps to CSP `connect-src` directive
     *
     * @example
     * ["https://api.weather.com", "wss://realtime.service.com"]
     */
    connectDomains?: string[],
    /**
     * Origins for static resources (images, scripts, stylesheets, fonts, media)
     *
     * - Empty or omitted = no external resources (secure default)
     * - Wildcard subdomains supported: `https://*.example.com`
     * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src`, `media-src` directives
     *
     * @example
     * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
     */
    resourceDomains?: string[],
  },
  /**
   * Dedicated origin for widget
   *
   * Optional domain for the widget's sandbox origin. Useful when widgets need
   * dedicated origins for API key allowlists or cross-origin isolation.
   *
   * If omitted, Host uses default sandbox origin.
   *
   * @example
   * "https://weather-widget.example.com"
   */
  domain?: string,
  /**
   * Visual boundary preference
   *
   * Boolean indicating the UI prefers a visible border. Useful for widgets
   * that might blend with host background.
   *
   * - `true`: Request visible border (host decides styling)
   * - `false` or omitted: No preference
   */
  prefersBorder?: boolean,
}
```

The resource content is returned via `resources/read`:

```typescript
// resources/read response for UI resource
{
  contents: [{
    uri: string;                  // Matching UI resource URI
    mimeType: "text/html;profile=mcp-app";  // MUST be "text/html;profile=mcp-app"
    text?: string;                // HTML content as string
    blob?: string;                // OR base64-encoded HTML
    _meta?: {
      ui?: {
        csp?: {
          connectDomains?: string[];  // Origins for fetch/XHR/WebSocket
          resourceDomains?: string[]; // Origins for images, scripts, etc
        };
        domain?: string;
        prefersBorder?: boolean;
      };
    };
  }];
}
```

#### Content Requirements:

- URI MUST start with `ui://` scheme
- `mimeType` MUST be `text/html;profile=mcp-app` (other types reserved for future extensions)
- Content MUST be provided via either `text` (string) or `blob` (base64-encoded)
- Content MUST be valid HTML5 document

#### Host Behavior:

- **CSP Enforcement:** Host MUST construct CSP headers based on declared domains
- **Restrictive Default:** If `ui.csp` is omitted, Host MUST use:

  ```
  default-src 'none';
  script-src 'self' 'unsafe-inline';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;
  media-src 'self' data:;
  connect-src 'none';
  ```

- **No Loosening:** Host MAY further restrict but MUST NOT allow undeclared domains
- **Audit Trail:** Host SHOULD log CSP configurations for security review

Example:

```json
// Resource declaration
{
  "uri": "ui://weather-server/dashboard-template",
  "name": "weather_dashboard",
  "description": "Interactive weather dashboard widget",
  "mimeType": "text/html;profile=mcp-app"
}

// Resource content with metadata
{
  "contents": [{
    "uri": "ui://weather-server/dashboard-template",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<!DOCTYPE html><html>...</html>",
    "_meta": {
      "ui" : {
        "csp": {
          "connectDomains": ["https://api.openweathermap.org"],
          "resourceDomains": ["https://cdn.jsdelivr.net"]
        },
        "prefersBorder": true
      }
    }
  }]
}
```

### Resource Discovery

Tools are associated with UI resources through the `_meta` field:

```typescript
interface Tool {
  name: string;
  description: string;
  inputSchema: object;
  _meta?: {
    // Required: URI of the UI resource to use for rendering
    "ui/resourceUri"?: string;
  };
}
```

Example:

```json
{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" }
    }
  },
  "_meta": {
    "ui/resourceUri": "ui://weather-server/dashboard-template"
  }
}
```

#### Behavior:

- If `ui/resourceUri` is present and host supports MCP Apps, host renders tool results using the specified UI resource
- If host does not support MCP Apps, tool behaves as standard tool (text-only fallback)
- Resource MUST exist on the server
- Host MUST use `resources/read` to fetch the referenced resource URI.
- Host MAY prefetch and cache UI resource content for performance optimization
- Since UI resources are primarily discovered through tool metadata, Servers MAY omit UI-only resources from `resources/list` and `notifications/resources/list_changed`

#### Benefits:

- **Performance:** Host can preload templates before tool execution
- **Security:** Host can review UI templates during connection setup
- **Caching:** Separate template (static) from data (dynamic)
- **Auditability:** All UI resources are enumerable and inspectable

### Communication Protocol

MCP Apps uses JSON-RPC 2.0 over `postMessage` for iframe-host communication. UI capabilities (e.g., tool call, prompt, etc.) will reuse MCP’s existing protocol. In the future, we may choose to enrich the communication protocol with additional MCP capabilities.

### Transport Layer

Conceptually, UI iframes act as MCP clients, connecting to the host via a `postMessage` transport:

```typescript
// UI iframe initializes MCP client
const transport = new MessageTransport(window.parent);
const client = new Client({ name: "ui-widget", version: "1.0.0" });
await client.connect(transport);
```

Note that you don’t need an SDK to “talk MCP” with the host:

```typescript
let nextId = 1;
function sendRequest(method: string, params: any) {
  const id = nextId++;
  window.parent.postMessage({ jsonrpc: "2.0", id, method, params }, '*');
  return new Promise((resolve, reject) => {
    window.addEventListener('message', function listener(event) {
      const data: JSONRPCMessage = event.data;
      if (event.data?.id === id) {
        window.removeEventListener('message', listener);
        if (event.data?.result) {
          resolve(event.data?.result);
        } else if (event.data?.error) {
          reject(new Error(event.data.error));
        }
      } else {
        reject(new Error(`Unsupported message: ${JSON.stringify(data)}`));
      }
    });
  });
}
function sendNotification(method: string, params: any) {
  window.parent.postMessage({ jsonrpc: "2.0", method, params }, '*');
}
function onNotification(method: string, handler: (params: any) => void) {
  window.addEventListener('message', function listener(event) {
    if (event.data?.method === method) {
      handler(event.data.params);
    }
  });
}


const initializeResult = await sendRequest("initialize", {
  capabilities: {},
  clientInfo: {name: "My UI", version: "1.0.0"},
  protocolVersion: "2025-06-18",
});
```

Hosts act as MCP servers (that can proxy the actual MCP server), receiving and handling requests from UI iframes.

### Sandbox proxy

If the Host is a web page, it MUST wrap the Guest UI and communicate with it through an intermediate Sandbox proxy.

1. The Host and the Sandbox MUST have different origins.
2. The Sandbox MUST have the following permissions: `allow-scripts`, `allow-same-origin`.
3. The Sandbox MUST send a `ui/notifications/sandbox-ready` notification to the host when it’s ready to process an `ui/sandbox-resource-ready` notification.
4. Once the Sandbox is ready, the Host MUST send the raw HTML resource to load in a `ui/notifications/sandbox-resource-ready` notification.
5. The Sandbox MUST load the raw HTML of the Guest UI with CSP settings that:
   - Enforce the domains declared in `ui.csp` metadata
   - Prevent nested iframes (`frame-src 'none'`)
   - Block dangerous features (`object-src 'none'`, `base-uri 'self'`)
   - Apply restrictive defaults if no CSP metadata is provided
6. The Sandbox MUST forward messages sent by the Host to the Guest UI, and vice versa, for any method that doesn’t start with `ui/notifications/sandbox-`. This includes lifecycle messages, e.g., `ui/initialize` request & `ui/notifications/initialized` notification both sent by the Guest UI. The Host MUST NOT send any request or notification to the Guest UI before it receives an `initialized` notification.
7. The Sandbox SHOULD NOT create/send any requests to the Host or to the Guest UI (this would require synthesizing new request ids).
8. The Host MAY forward any message from the Guest UI (coming via the Sandbox) to the MCP Apps server, for any method that doesn’t start with `ui/`. While the Host SHOULD ensure the Guest UI’s MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.

### Standard MCP Messages

UI iframes can use the following subset of standard MCP protocol messages:

**Tools:**

- `tools/call` - Execute a tool on the MCP server

**Resources:**

- `resources/read` - Read resource content

**Notifications:**

- `notifications/message` - Log messages to host

**Lifecycle:**

- `ui/initialize` → `ui/notifications/initialized` - MCP-like handshake (replaces custom iframe-ready pattern in MCP-UI)
- `ping` - Connection health check

### Host Context in `McpUiInitializeResult`

When the Guest UI sends an `ui/initialize` request to the Host, the Host SHOULD include UI-specific context in the `McpUiInitializeResult`’s `hostContext` field:

```typescript
interface HostContext {
  /** Metadata of the tool call that instantiated the App */
  toolInfo?: {
    /** JSON-RPC id of the tools/call request */
    id?: RequestId,
    /** Contains name, inputSchema, etc… */
    tool: Tool,
  };
  /** Current color theme preference */
  theme?: "light" | "dark";
  /** How the UI is currently displayed */
  displayMode?: "inline" | "fullscreen" | "pip";
  /** Display modes the host supports */
  availableDisplayModes?: string[];
  /** Current and maximum dimensions available to the UI */
  viewport?: {
    width: number;
    height: number;
    maxHeight?: number;
    maxWidth?: number;
  };
  /** User's language/region preference (BCP 47, e.g., "en-US") */
  locale?: string;
  /** User's timezone (IANA, e.g., "America/New_York") */
  timeZone?: string;
  /** Host application identifier */
  userAgent?: string;
  /** Platform type for responsive design */
  platform?: "web" | "desktop" | "mobile";
  /** Device capabilities such as touch */
  deviceCapabilities?: {
    touch?: boolean;
    hover?: boolean;
  }
  /** Safe area boundaries in pixels */
  safeAreaInsets?: {
    top: number;
    right: number;
    bottom: number;
    left: number;
  };
}
```

All fields are optional. Hosts SHOULD provide relevant context. Guest UIs SHOULD handle missing fields gracefully.

Example:

```json
// Host responds with McpUiInitializeResult
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "hostCapabilities": { /* ... */ },
    "hostInfo": { "name": "claude-desktop", "version": "1.0.0" },
    "hostContext": {
      "theme": "dark",
      "displayMode": "inline",
      "viewport": { "width": 400, "height": 300 }
    }
  }
}
```

### MCP Apps Specific Messages

MCP Apps introduces additional JSON-RPC methods for UI-specific functionality:

#### Requests (UI → Host)

`ui/open-link` - Request host to open external URL

```typescript
// Request
{
  jsonrpc: "2.0",
  id: 1,
  method: "ui/open-link",
  params: {
    url: string  // URL to open in host's browser
  }
}

// Success Response
{
  jsonrpc: "2.0",
  id: 1,
  result: {}  // Empty result on success
}

// Error Response (if denied or failed)
{
  jsonrpc: "2.0",
  id: 1,
  error: {
    code: -32000,  // Implementation-defined error
    message: "Link opening denied by user" | "Invalid URL" | "Policy violation"
  }
}
```

Host SHOULD open the URL in the user's default browser or a new tab.

`ui/message` - Send message content to the host's chat interface

```typescript
// Request
{
  jsonrpc: "2.0",
  id: 2,
  method: "ui/message",
  params: {
    role: "user",
    content: {
      type: "text",
      text: string
    }
  }
}

// Success Response
{
  jsonrpc: "2.0",
  id: 2,
  result: {}  // Empty result on success
}

// Error Response (if denied or failed)
{
  jsonrpc: "2.0",
  id: 2,
  error: {
    code: -32000,  // Implementation-defined error
    message: "Message sending denied" | "Invalid message format"
  }
}
```

Host SHOULD add the message to the conversation thread, preserving the specified role.

#### Notifications (Host → UI)

`ui/notifications/tool-input` - Host MUST send this notification with the complete tool arguments after the Guest UI's initialize request completes.

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-input",
  params: {
    arguments: Record<string, unknown>  // Tool input arguments
  }
}
```

Host sends this notification after the Guest UI's initialize request completes, when tool arguments become available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`.

`ui/notifications/tool-input-partial` - Host MAY send this notification zero or more times while the agent is streaming tool arguments, before `ui/notifications/tool-input` is sent.

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-input-partial",
  params: {
    arguments: Record<string, unknown>  // Tool input arguments
  }
}
```

The arguments object represents best-effort recovery of incomplete JSON, with unclosed structures automatically closed to produce valid JSON. Host behavior (optional):

- MAY parse the agent's partial JSON output by closing unclosed brackets/braces
- MAY send recovered arguments as they become available during streaming
- MUST stop sending once `ui/notifications/tool-input` is sent with complete arguments

Guest UI behavior (optional):

- MAY ignore these notifications entirely
- MAY render progressive loading/streaming states based on available fields
- MUST NOT rely on partial arguments for critical operations
- SHOULD gracefully handle missing or changing fields between notifications

`ui/notifications/tool-result` - Tool execution result

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-result",
  params: CallToolResult  // Standard MCP type
}
```

Host MUST send this notification when tool execution completes (if UI is displayed during tool execution).

`ui/notifications/tool-cancelled` - Tool execution was cancelled

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-cancelled",
  params: {
    reason: string
  }
}
```

Host MUST send this notification if the tool execution was cancelled, for any reason (which can optionally be specified), including user action, sampling error, classifier intervention, etc.

`ui/resource-teardown` - Host notifies UI before teardown

```typescript
{
  jsonrpc: "2.0",
  id: 1,
  method: "ui/resource-teardown",
  params: {
    reason: string
  }
}

// Success Response
{
  jsonrpc: "2.0",
  id: 1,
  result: {}  // Empty result on success
}

// Error Response (if failed)
{
  jsonrpc: "2.0",
  id: 1,
  error: {
    code: -32000,  // Implementation-defined error
    message: "Teardown error"
  }
}
```

Host MUST send this notification before tearing down the UI resource, for any reason, including user action, resource re-allocation, etc. The Host MAY specify the reason.
Host SHOULD wait for a response before tearing down the resource (to prevent data loss).

`ui/notifications/size-changed` - UI’s size changed

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/size-changed",
  params: {
    width: number,   // Viewport width in pixels
    height: number   // Viewport height in pixels
  }
}
```

Guest UI SHOULD send this notification when rendered content body size changes (e.g. using ResizeObserver API to report up to date size).

`ui/notifications/host-context-changed` - Host context has changed

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/host-context-changed",
  params: Partial<HostContext>  // See HostContext type above
}
```

Host MAY send this notification when any context field changes (e.g., theme toggle, display mode change, device orientation change, window/panel resize). This notification contains partial updates - Guest UI SHOULD merge received fields with its current context state.

#### Reserved Messages (Sandbox Proxy)

These messages are reserved for web-based hosts that implement the recommended double-iframe sandbox architecture:

`ui/notifications/sandbox-ready` (Sandbox Proxy → Host) - Sandbox proxy is ready

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/sandbox-ready",
  params: {}
}
```

`ui/notifications/sandbox-resource-ready` (Host → Sandbox Proxy) - HTML resource ready to load

```typescript
{
  jsonrpc: "2.0",
  method: "ui/notifications/sandbox-resource-ready",
  params: {
    html: string,        // HTML content to load
    sandbox: string      // Optional override for inner iframe `sandbox` attribute
  }
}
```

These messages facilitate the communication between the outer sandbox proxy iframe and the host, enabling secure loading of untrusted HTML content.

### Lifecycle

The typical lifecycle for rendering a UI resource:

#### 1. Connection & Discovery

```mermaid
sequenceDiagram
  participant H as Host
  participant S as MCP Server

  autonumber
  S -->> H: resources/list (includes ui:// resources)
  S -->> H: tools/list (includes tools with ui/resourceUri metadata)
```

#### 2. UI Initialization (Desktop/Native Hosts)

```mermaid
sequenceDiagram
  participant H as Host
  participant UI as Guest UI (iframe)
  participant P as Sandbox Proxy
  participant S as MCP Server

  autonumber
  par UI Tool call
    H ->> S: tools/call to Tool with ui/resourceUri metadata
  and UI initialization
    alt Desktop/Native hosts
      H ->> H: Render Guest UI in an iframe (HTML from the ui:// resource)
    else Web hosts
      H ->> H: Render Sandbox Proxy in an iframe (different origin)
      P ->> H: ui/notifications/sandbox-ready
      H -->> P: ui/notifications/sandbox-resource-ready (HTML content)
      P -> P: Render inner iframe with HTML

    end
    UI ->> H: ui/initialize
    H -->> UI: McpUiInitializeResult (e.g., host-context, capabilities, etc.)
    UI ->> H: ui/notifications/initialized
    opt Stream Tool input to UI
      H -->> UI: ui/notifications/tool-input-partial (0..n)
    end
    H -->> UI: ui/notifications/tool-input (complete)
  end
  alt Tool complete
    H -->> UI: ui/notifications/tool-result
  else Tool cancelled
    H -->> UI: ui/notifications/tool-cancelled
  end
```

Note: when the Guest UI is rendered inside a sandbox, the sandbox transparently passes messages between the Guest UI and the Host, except for messages named `ui/notifications/sandbox-*`.

#### 3. Interactive Phase

```mermaid
sequenceDiagram
  actor U as User / Agent
  participant H as Host
  participant UI as Guest UI (iframe)
  participant S as MCP Server
  loop Interactive phase
    U ->> UI: interaction (e.g., click)
    alt Tool call
      UI ->> H: tools/call
      H ->> S: tools/call
      opt Stream Tool input to UI
        H -->> UI: ui/notifications/tool-input-partial (0..n)
      end
      H -->> UI: ui/notifications/tool-input (complete)
      H-->>UI: ui/notifications/tool-result
    else Message
      UI ->> H: ui/message
      H -->> H: Process message and follow up
    else Notify
      UI ->> H: notifications/message
      H ->> H: Process notification and store in context
    else Resource read
      UI ->> H: resources/read
      H ->> S: resources/read
      S --> H: resources/read response
      H --> UI: resources/read response
    end
    opt UI notifications
      UI ->> H: notifications (e.g., ui/notifications/size-changed)
    end
    opt Host notifications
      H ->> UI: notifications (e.g., ui/notifications/host-context-changed)
    end
  end
```

#### 4. Cleanup

```mermaid
sequenceDiagram
  participant H as Host
  participant UI as Guest UI (iframe)
  H ->> UI: ui/resource-teardown
  UI --> UI: Graceful termination
  UI -->> H: ui/resource-teardown response
  H -x H: Tear down iframe and listeners
```

Note: Cleanup may be triggered at any point in the lifecycle following UI initialization.

#### Key Differences from Pre-SEP MCP-UI:

- Handshakes using MCP-like `ui/initialize` / `ui/notifications/initialized` messages instead of `iframe-ready`
- Capabilities negotiated via `McpUiInitializeResult`
- Tool data passed via notifications

### Data Passing

Tool execution results are passed to the UI through two mechanisms:

#### 1. Tool Input (via `ui/notifications/tool-input` notification)

The original tool call arguments:

```typescript
// Tool was called with (JSON-RPC request from Host to Server):
{
  jsonrpc: "2.0",
  id: 1,
  method: "tools/call",
  params: {
    name: "get_weather",
    arguments: {
      location: "San Francisco"
    }
  }
}

// UI receives (JSON-RPC notification from Host to UI):
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-input",
  params: {
    arguments: {
      location: "San Francisco"
    }
  }
}
```

#### 2. Tool Result (via `ui/notifications/tool-result` notification)

The tool's execution result:

```typescript
// Server returns from tool execution (JSON-RPC response):
{
  jsonrpc: "2.0",
  id: 1,  // Matches the tools/call request id
  result: {
    content: [
      { type: "text", text: "Current weather: Sunny, 72°F" }
    ],
    structuredContent: {
      temperature: 72,
      conditions: "sunny",
      humidity: 45
    },
    _meta: {
      timestamp: "2025-11-10T15:30:00Z",
      source: "weather-api"
    }
  }
}

// UI receives (JSON-RPC notification):
{
  jsonrpc: "2.0",
  method: "ui/notifications/tool-result",
  params: {
    content: [
      { type: "text", text: "Current weather: Sunny, 72°F" }
    ],
    structuredContent: {
      temperature: 72,
      conditions: "sunny",
      humidity: 45
    },
    _meta: {
      timestamp: "2025-11-10T15:30:00Z",
      source: "weather-api"
    }
  }
}
```

**Best Practices:**

- `content`: Text representation for model context and text-only hosts
- `structuredContent`: Structured data optimized for UI rendering (not added to model context)
- `_meta`: Additional metadata (timestamps, version info, etc.) not intended for model context

#### 3. Interactive Updates

UI can request fresh data by calling tools:

```typescript
// UI requests updated data
await client.callTool("get_weather", { location: "New York" });

// Result returned via standard tools/call response
```

This pattern enables interactive, self-updating widgets.

Note: The called tool may not appear in `tools/list` responses. MCP servers MAY expose private tools specifically designed for UI interaction that are not visible to the agent. UI implementations SHOULD attempt to call tools by name regardless of discoverability. The specification for Private Tools will be covered in a future SEP.

### Client\<\>Server Capability Negotiation

Clients and servers negotiate MCP Apps support through the standard MCP extensions capability mechanism (defined in SEP-1724).

#### Client (Host) Capabilities

Clients advertise MCP Apps support in the initialize request using the extension identifier `io.modelcontextprotocol/ui`:

```json
{
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "extensions": {
        "io.modelcontextprotocol/ui": {
          "mimeTypes": ["text/html;profile=mcp-app"]
        }
      }
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    }
  }
}
```

**Extension Settings:**

- `mimeTypes`: Array of supported content types (REQUIRED, e.g., `["text/html;profile=mcp-app"]`)

Future versions may add additional settings:

- `features`: Specific feature support (e.g., `["streaming", "persistence"]`)
- `sandboxPolicies`: Supported sandbox attribute configurations

#### Server Behavior

Servers SHOULD check client (host would-be) capabilities before registering UI-enabled tools:

```typescript
const hasUISupport =
  clientCapabilities?.extensions?.["io.modelcontextprotocol/ui"]?.mimeTypes?.includes("text/html;profile=mcp-app");

if (hasUISupport) {
  // Register tools with UI templates
  server.registerTool("get_weather", {
    description: "Get weather with interactive dashboard",
    inputSchema: { /* ... */ },
    _meta: {
      "ui/resourceUri": "ui://weather-server/dashboard"
    }
  });
} else {
  // Register text-only version
  server.registerTool("get_weather", {
    description: "Get weather as text",
    inputSchema: { /* ... */ }
    // No UI metadata
  });
}
```

**Graceful Degradation:**

- Servers SHOULD provide text-only fallback behavior for all UI-enabled tools
- Tools MUST return meaningful content array even when UI is available
- Servers MAY register different tool variants based on host capabilities

### Extensibility

This specification defines the Minimum Viable Product (MVP) for MCP Apps. Future extensions may include:

**Content Types (deferred from MVP):**

- `externalUrl`: Embed external web applications (e.g., `text/uri-list`)

**Advanced Features (see Future Considerations):**

- Support multiple UI resources in a tool response
- State persistence and restoration
- Custom sandbox policies per resource
- Widget-to-widget communication
- Screenshot/preview generation APIs

## Rationale

This proposal synthesizes feedback from the UI CWG and MCP-UI community, host implementors, and lessons from similar solutions. The guiding principle of this proposal is to start lean and expand in the future. There are breaking changes from existing solutions, which will be addressed via the MCP-UI SDK during the migration period.

### Design Decisions

#### 1. Predeclared Resources vs. Inline Embedding

**Decision:** Require UI resources to be registered and referenced in tool metadata.

**Rationale:**

- Enables hosts to prefetch templates before tool execution, improving performance
- Separates presentation (template) from data (tool results), improving caching
- Allows hosts to review UI templates
- Aligns with MCP's resource discovery pattern

**Alternatives considered:**

- **Embedded resources:** Current MCP-UI approach, where resources are returned in tool results. Although it's more convenient for server development, it was deferred due to the gaps in performance optimization and the challenges in the UI review process.
- **Resource links:** Predeclare the resources but return links in tool results. Deferred due to the gaps in performance optimization.

#### 2. Host communication via MCP Transport

**Decision:** Use MCP's JSON-RPC base protocol over postMessage instead of custom message format.

**Rationale:**

- Reuses existing MCP infrastructure (type definitions, error handling, timeouts)
- UI developers can use standard MCP SDK (`@modelcontextprotocol/sdk`) or alternatives
- Automatic compatibility with future MCP features (long-running tools, sampling, etc.)
- Better auditability through structured JSON-RPC messages
- Reduces maintenance burden (no parallel protocol to evolve)

**Alternatives considered:**

- **Custom message protocol:** Current MCP-UI approach with message types like tool, intent, prompt, etc. These message types can be translated to a subset of the proposed JSON-RPC messages.
- **Global API object:** Rejected because it requires host-specific injection and doesn't work with external iframe sources. Syntactic sugar may still be added on the server/UI side.

#### 3. Support Raw HTML Content Type

**Decision:** MVP supports only `text/html;profile=mcp-app` (rawHtml), with other types explicitly deferred.

**Rationale:**

- HTML is universally supported and well-understood
- Simplest security model (standard iframe sandbox)
- Allows screenshot/preview generation (e.g., via html2canvas)
- Sufficient for most observed use cases
- Provides clear baseline for future extensions

**Alternatives considered:**

- **Include external URLs in MVP:** This is one of the easiest content types for servers to adopt, as it's possible to embed regular apps. However, it was deferred due to concerns around model visibility, inability to screenshot content, and review process.
- **Support multiple content types:** Deferred to maintain a lean MVP.

### Backward Compatibility

The proposal builds on the existing core protocol. There are no incompatibilities.

### Reference Implementation

The MCP-UI project serves as a reference implementation demonstrating the core concept, though it uses pre-SEP patterns.

Olivier Chafik has developed a prototype demonstrating the pattern described in this SEP.

## Security Implications

Hosting interactive UI content from potentially untrusted MCP servers requires careful security consideration.

### Threat Model

Attackers may use the embedded UI in different scenarios. For example:

- Malicious server delivers harmful HTML content
- Compromised UI attempts to escape sandbox
- UI attempts unauthorized tool execution
- UI exfiltrates sensitive host data
- UI performs phishing or social engineering

### Mitigations

#### 1. Iframe Sandboxing

All UI content MUST be rendered in sandboxed iframes with restricted permissions.

The sandbox limits the UI from accessing the host or manipulating it. All communication with the host is done via `postMessage`, where the host is in control.

#### 2. Auditable Communication

All UI-to-host communication goes through auditable MCP JSON-RPC messages.

**Host behavior:**

- Validate all incoming messages from UI iframes
- Reject malformed message types
- Log UI-initiated RPC calls for security review

#### 3. Predeclared Resource Review

Hosts receive UI templates during connection setup, before tool execution.

**Host behavior:**

- Review HTML content for obvious malicious patterns
- Generate hash/signature for resources
- Warn users about suspicious content
- Implement allowlists/blocklists based on resource hashes

#### 4. Content Security Policy Enforcement

Hosts MUST enforce Content Security Policies based on resource metadata.

**CSP Construction from Metadata:**

```typescript
const csp = resource._meta?.ui?.csp;

const cspValue = `
  default-src 'none';
  script-src 'self' 'unsafe-inline';
  style-src 'self' 'unsafe-inline';
  connect-src 'self' ${csp?.connectDomains?.join(' ') || ''};
  img-src 'self' data: ${csp?.resourceDomains?.join(' ') || ''};
  font-src 'self' ${csp?.resourceDomains?.join(' ') || ''};
  media-src 'self' data: ${csp?.resourceDomains?.join(' ') || ''};
  frame-src 'none';
  object-src 'none';
  base-uri 'self';
`;
```

**Security Requirements:**

- Host MUST block connections to undeclared domains
- Host SHOULD warn users when UI requires external domain access
- Host MAY implement global domain allowlists/blocklists

### Other risks

- **Social engineering:** UI can still display misleading content. Hosts should clearly indicate sandboxed UI boundaries.
- **Resource consumption:** Malicious UI can consume CPU/memory. Hosts should implement resource limits.

## Reservations in MCP

- The resource prefix `ui://` will be reserved for MCP Apps
- The label `io.modelcontextprotocol/ui` is reserved