MCP Apps SDK
This documentation covers MCP Apps SDK v1.5.0 (@modelcontextprotocol/ext-apps).
import type {
McpUiInitializeRequest,
McpUiInitializeResult,
McpUiOpenLinkRequest,
McpUiOpenLinkResult,
McpUiDownloadFileRequest,
McpUiDownloadFileResult,
McpUiMessageRequest,
McpUiMessageResult,
McpUiUpdateModelContextRequest,
McpUiRequestDisplayModeRequest,
McpUiRequestDisplayModeResult,
McpUiResourceTeardownRequest,
McpUiResourceTeardownResult,
McpUiToolInputNotification,
McpUiToolInputPartialNotification,
McpUiToolResultNotification,
McpUiToolCancelledNotification,
McpUiHostContextChangedNotification,
McpUiInitializedNotification,
McpUiSizeChangedNotification,
McpUiRequestTeardownNotification,
AppRequest,
AppNotification,
AppResult,
AppEventMap,
} from "@modelcontextprotocol/ext-apps";
Request / Result Types
Initialization
| Type | Method | Direction | Description |
|---|
McpUiInitializeRequest | ui/initialize | View → Host | App info, capabilities, protocol version |
McpUiInitializeResult | — | Host → View | Protocol version, host info, capabilities, context |
View → Host Requests
| Type | Method | Description |
|---|
McpUiOpenLinkRequest | ui/open-link | Open URL: { url: string } |
McpUiOpenLinkResult | — | { isError?: boolean } |
McpUiDownloadFileRequest | ui/download-file | Download file: { contents: (EmbeddedResource | ResourceLink)[] } |
McpUiDownloadFileResult | — | { isError?: boolean } |
McpUiMessageRequest | ui/message | Send message: { role: "user"; content: ContentBlock[] } |
McpUiMessageResult | — | { isError?: boolean } |
McpUiUpdateModelContextRequest | ui/update-model-context | Update context: { content?; structuredContent? } |
McpUiRequestDisplayModeRequest | ui/request-display-mode | Request mode: { mode: McpUiDisplayMode } |
McpUiRequestDisplayModeResult | — | { mode: McpUiDisplayMode } (actual mode set) |
Host → View Requests
| Type | Method | Description |
|---|
McpUiResourceTeardownRequest | ui/resource-teardown | Graceful shutdown: {} |
McpUiResourceTeardownResult | — | {} |
Notification Types
Host → View
| Type | Method | Description |
|---|
McpUiToolInputNotification | ui/notifications/tool-input | Complete tool arguments |
McpUiToolInputPartialNotification | ui/notifications/tool-input-partial | Streaming partial arguments |
McpUiToolResultNotification | ui/notifications/tool-result | Tool execution result |
McpUiToolCancelledNotification | ui/notifications/tool-cancelled | Tool execution cancelled |
McpUiHostContextChangedNotification | ui/notifications/host-context-changed | Partial context update |
View → Host
| Type | Method | Description |
|---|
McpUiInitializedNotification | ui/notifications/initialized | Initialization complete |
McpUiSizeChangedNotification | ui/notifications/size-changed | UI size change: { width?; height? } |
McpUiRequestTeardownNotification | ui/notifications/request-teardown | App requests host to tear it down |
Union Types
These union types group all possible message types in the protocol. They are useful for building generic message handlers, routers, or middleware that processes any protocol message.
| Type | Description |
|---|
AppRequest | Union of all request types: initialization, View → Host requests (openLink, downloadFile, sendMessage, updateModelContext, requestDisplayMode, sendLog, sendSizeChanged), proxied MCP server requests (callServerTool, readServerResource, listServerResources), Host → View requests (resourceTeardown), and ping |
AppNotification | Union of all notification types in both directions: Host → View (toolInput, toolInputPartial, toolResult, toolCancelled, hostContextChanged) and View → Host (initialized, sizeChanged, requestTeardown) |
AppResult | Union of all result types corresponding to each request type |
import type { AppRequest, AppNotification, AppResult } from "@modelcontextprotocol/ext-apps";
// Example: generic message logger
function logMessage(msg: AppRequest | AppNotification | AppResult) {
console.log(`[${msg.method}]`, msg);
}
Event Maps
Type-safe maps of event names to notification params types, used by addEventListener / removeEventListener.
import type { AppEventMap } from "@modelcontextprotocol/ext-apps";
import type { AppBridgeEventMap } from "@modelcontextprotocol/ext-apps/app-bridge";
| Type | Side | Events |
|---|
AppEventMap | View (App) | toolinput, toolinputpartial, toolresult, toolcancelled, hostcontextchanged |
AppBridgeEventMap | Host (AppBridge) | sizechange, sandboxready, initialized, requestteardown, loggingmessage |
Method Constants
Type-safe string constants for protocol method names.
import {
INITIALIZE_METHOD,
INITIALIZED_METHOD,
OPEN_LINK_METHOD,
DOWNLOAD_FILE_METHOD,
MESSAGE_METHOD,
REQUEST_DISPLAY_MODE_METHOD,
REQUEST_TEARDOWN_METHOD,
RESOURCE_TEARDOWN_METHOD,
SIZE_CHANGED_METHOD,
TOOL_INPUT_METHOD,
TOOL_INPUT_PARTIAL_METHOD,
TOOL_RESULT_METHOD,
TOOL_CANCELLED_METHOD,
HOST_CONTEXT_CHANGED_METHOD,
} from "@modelcontextprotocol/ext-apps";
| Constant | Value |
|---|
INITIALIZE_METHOD | "ui/initialize" |
INITIALIZED_METHOD | "ui/notifications/initialized" |
OPEN_LINK_METHOD | "ui/open-link" |
DOWNLOAD_FILE_METHOD | "ui/download-file" |
MESSAGE_METHOD | "ui/message" |
REQUEST_DISPLAY_MODE_METHOD | "ui/request-display-mode" |
REQUEST_TEARDOWN_METHOD | "ui/notifications/request-teardown" |
RESOURCE_TEARDOWN_METHOD | "ui/resource-teardown" |
SIZE_CHANGED_METHOD | "ui/notifications/size-changed" |
TOOL_INPUT_METHOD | "ui/notifications/tool-input" |
TOOL_INPUT_PARTIAL_METHOD | "ui/notifications/tool-input-partial" |
TOOL_RESULT_METHOD | "ui/notifications/tool-result" |
TOOL_CANCELLED_METHOD | "ui/notifications/tool-cancelled" |
HOST_CONTEXT_CHANGED_METHOD | "ui/notifications/host-context-changed" |
Other Constants
| Constant | Value | Description |
|---|
LATEST_PROTOCOL_VERSION | "2026-01-26" | Current protocol version |
RESOURCE_MIME_TYPE | "text/html;profile=mcp-app" | MIME type for MCP App resources |
RESOURCE_URI_META_KEY | "ui/resourceUri" | Deprecated metadata key for tool-resource linkage |
EXTENSION_ID | "io.modelcontextprotocol/ui" | Extension identifier for capability negotiation |
Zod Schemas
Every type has a corresponding Zod schema exported for runtime validation. Schema names follow the pattern {TypeName}Schema (e.g., McpUiTheme → McpUiThemeSchema).
Core Type Schemas
import {
McpUiThemeSchema,
McpUiDisplayModeSchema,
McpUiHostContextSchema,
McpUiHostCapabilitiesSchema,
McpUiAppCapabilitiesSchema,
McpUiHostCssSchema,
McpUiHostStylesSchema,
McpUiSupportedContentBlockModalitiesSchema,
} from "@modelcontextprotocol/ext-apps";
| Schema | Validates |
|---|
McpUiThemeSchema | McpUiTheme — "light" or "dark" |
McpUiDisplayModeSchema | McpUiDisplayMode — "inline", "fullscreen", "pip" |
McpUiHostContextSchema | McpUiHostContext — theme, styles, locale, dimensions, etc. |
McpUiHostCapabilitiesSchema | McpUiHostCapabilities — host feature flags |
McpUiAppCapabilitiesSchema | McpUiAppCapabilities — app-declared features |
McpUiHostCssSchema | McpUiHostCss — host CSS (fonts) |
McpUiHostStylesSchema | McpUiHostStyles — style variables + CSS |
McpUiSupportedContentBlockModalitiesSchema | McpUiSupportedContentBlockModalities — text, image, audio, etc. |
Initialization Schemas
import {
McpUiInitializeRequestSchema,
McpUiInitializeResultSchema,
McpUiInitializedNotificationSchema,
} from "@modelcontextprotocol/ext-apps";
| Schema | Validates |
|---|
McpUiInitializeRequestSchema | McpUiInitializeRequest — View → Host init |
McpUiInitializeResultSchema | McpUiInitializeResult — Host → View init response |
McpUiInitializedNotificationSchema | McpUiInitializedNotification — View → Host init complete |
Request / Result Schemas
import {
McpUiOpenLinkRequestSchema,
McpUiOpenLinkResultSchema,
McpUiDownloadFileRequestSchema,
McpUiDownloadFileResultSchema,
McpUiMessageRequestSchema,
McpUiMessageResultSchema,
McpUiUpdateModelContextRequestSchema,
McpUiRequestDisplayModeRequestSchema,
McpUiRequestDisplayModeResultSchema,
McpUiResourceTeardownRequestSchema,
McpUiResourceTeardownResultSchema,
} from "@modelcontextprotocol/ext-apps";
| Schema | Validates |
|---|
McpUiOpenLinkRequestSchema | McpUiOpenLinkRequest — open URL request |
McpUiOpenLinkResultSchema | McpUiOpenLinkResult — open URL result |
McpUiDownloadFileRequestSchema | McpUiDownloadFileRequest — download file request |
McpUiDownloadFileResultSchema | McpUiDownloadFileResult — download file result |
McpUiMessageRequestSchema | McpUiMessageRequest — send message request |
McpUiMessageResultSchema | McpUiMessageResult — send message result |
McpUiUpdateModelContextRequestSchema | McpUiUpdateModelContextRequest — update context request |
McpUiRequestDisplayModeRequestSchema | McpUiRequestDisplayModeRequest — display mode request |
McpUiRequestDisplayModeResultSchema | McpUiRequestDisplayModeResult — display mode result |
McpUiResourceTeardownRequestSchema | McpUiResourceTeardownRequest — teardown request |
McpUiResourceTeardownResultSchema | McpUiResourceTeardownResult — teardown result |
Notification Schemas
import {
McpUiToolInputNotificationSchema,
McpUiToolInputPartialNotificationSchema,
McpUiToolResultNotificationSchema,
McpUiToolCancelledNotificationSchema,
McpUiHostContextChangedNotificationSchema,
McpUiSizeChangedNotificationSchema,
McpUiRequestTeardownNotificationSchema,
} from "@modelcontextprotocol/ext-apps";
| Schema | Validates |
|---|
McpUiToolInputNotificationSchema | McpUiToolInputNotification — tool arguments |
McpUiToolInputPartialNotificationSchema | McpUiToolInputPartialNotification — streaming partial arguments |
McpUiToolResultNotificationSchema | McpUiToolResultNotification — tool result |
McpUiToolCancelledNotificationSchema | McpUiToolCancelledNotification — tool cancelled |
McpUiHostContextChangedNotificationSchema | McpUiHostContextChangedNotification — context update |
McpUiSizeChangedNotificationSchema | McpUiSizeChangedNotification — size change |
McpUiRequestTeardownNotificationSchema | McpUiRequestTeardownNotification — app-initiated teardown request |
import {
McpUiResourceCspSchema,
McpUiResourcePermissionsSchema,
McpUiResourceMetaSchema,
McpUiToolVisibilitySchema,
McpUiToolMetaSchema,
} from "@modelcontextprotocol/ext-apps";
| Schema | Validates |
|---|
McpUiResourceCspSchema | McpUiResourceCsp — CSP configuration |
McpUiResourcePermissionsSchema | McpUiResourcePermissions — browser permissions |
McpUiResourceMetaSchema | McpUiResourceMeta — resource UI metadata |
McpUiToolVisibilitySchema | McpUiToolVisibility — tool visibility |
McpUiToolMetaSchema | McpUiToolMeta — tool UI metadata |
