This documentation covers MCP Apps SDK v1.7.4 (
@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) |
Proxied Requests
The host proxies select MCP requests between the View and the originating MCP server (or, for sampling, between the View and the host’s LLM). These reuse standard MCP request/result types from@modelcontextprotocol/sdk.
| Type | Method | Direction | Description |
|---|---|---|---|
CallToolRequest | tools/call | View → Server | Call a server tool. Used by callServerTool. |
CallToolResult | — | Server → View | Tool execution result. |
ReadResourceRequest | resources/read | View → Server | Read a server resource. Used by readServerResource. |
ReadResourceResult | — | Server → View | Resource contents. |
ListResourcesRequest | resources/list | View → Server | List server resources. Used by listServerResources. |
ListResourcesResult | — | Server → View | Resource list with optional cursor. |
CreateMessageRequest | sampling/createMessage | View → Host | LLM completion. Used by createSamplingMessage. |
CreateMessageResult / CreateMessageResultWithTools | — | Host → View | Sampling result. The WithTools variant carries tool_use blocks when params.tools is provided. |
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. Sent by requestTeardown. |
LoggingMessageNotification | notifications/message | Diagnostic log message. Sent by sendLog. |
ToolListChangedNotification | notifications/tools/list_changed | App-side tool list changed. Sent by sendToolListChanged after registerTool, enable, disable, or remove. |
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), proxied MCP server requests (callServerTool, readServerResource, listServerResources, listResourceTemplates, listPrompts, listTools), proxied LLM sampling (createSamplingMessage), Host → View requests (resourceTeardown), and ping |
AppNotification | Union of all notification types in both directions: Host → View (toolInput, toolInputPartial, toolResult, toolCancelled, hostContextChanged, sandboxResourceReady, resourceListChanged, promptListChanged) and View → Host (initialized, sizeChanged, sandboxProxyReady, requestTeardown, toolListChanged, loggingMessage) |
AppResult | Union of all result types corresponding to each request type, plus EmptyResult |
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 notificationparams 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 |
Metadata Schemas
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 |