MCP Apps Protocol Reference - Types & Schemas

MCP Apps SDK

This reference covers MCP Apps SDK v2.0.3, which current sunpeak releases use. Version 2.0 keeps the same View protocol, uses split peer packages, deprecates the union types below, and broadens some core schemas. See the SDK 2.0 migration guide.

import type {
  McpUiTheme,
  McpUiDisplayMode,
  McpUiStyleVariableKey,
  McpUiStyles,
  McpUiHostCss,
  McpUiHostStyles,
  McpUiInitializeRequest,
  McpUiInitializeResult,
  McpUiOpenLinkRequest,
  McpUiOpenLinkResult,
  McpUiDownloadFileRequest,
  McpUiDownloadFileResult,
  McpUiMessageRequest,
  McpUiMessageResult,
  McpUiUpdateModelContextRequest,
  McpUiRequestDisplayModeRequest,
  McpUiRequestDisplayModeResult,
  McpUiResourceTeardownRequest,
  McpUiResourceTeardownResult,
  McpUiToolInputNotification,
  McpUiToolInputPartialNotification,
  McpUiToolResultNotification,
  McpUiToolCancelledNotification,
  McpUiHostContextChangedNotification,
  McpUiInitializedNotification,
  McpUiSizeChangedNotification,
  McpUiRequestTeardownNotification,
  McpUiSandboxProxyReadyNotification,
  McpUiSandboxResourceReadyNotification,
  McpUiSupportedContentBlockModalities,
  McpUiHostContext,
  McpUiHostCapabilities,
  McpUiAppCapabilities,
  McpUiResourceCsp,
  McpUiResourcePermissions,
  McpUiResourceMeta,
  McpUiToolVisibility,
  McpUiToolMeta,
  McpUiClientCapabilities,
  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/client in View and Host code, or @modelcontextprotocol/server in server code.

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
`McpUiSandboxResourceReadyNotification`	`ui/notifications/sandbox-resource-ready`	Resource HTML is ready for a sandbox proxy

View → Host

Type	Method	Description
`McpUiInitializedNotification`	`ui/notifications/initialized`	Initialization complete
`McpUiSizeChangedNotification`	`ui/notifications/size-changed`	UI size change: `{ width?; height? }`
`McpUiSandboxProxyReadyNotification`	`ui/notifications/sandbox-proxy-ready`	Sandbox proxy is ready to receive resource HTML
`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. The dynamic registry sends it automatically; custom `onlisttools` implementations can use `sendToolListChanged`.

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) {
  if ("method" in msg) {
    console.log(`[${msg.method}]`, msg);
  } else {
    console.log("[result]", 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,
  SANDBOX_PROXY_READY_METHOD,
  SANDBOX_RESOURCE_READY_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"`
`SANDBOX_PROXY_READY_METHOD`	`"ui/notifications/sandbox-proxy-ready"`
`SANDBOX_RESOURCE_READY_METHOD`	`"ui/notifications/sandbox-resource-ready"`
`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,
  McpUiSandboxProxyReadyNotificationSchema,
  McpUiSandboxResourceReadyNotificationSchema,
  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
`McpUiSandboxProxyReadyNotificationSchema`	`McpUiSandboxProxyReadyNotification` — sandbox proxy ready
`McpUiSandboxResourceReadyNotificationSchema`	`McpUiSandboxResourceReadyNotification` — resource HTML ready
`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

Overview

App

MCP

React

Server

Styling

Types

MCP Apps Protocol Reference - Types & Schemas

Request / Result Types

Initialization

View → Host Requests

Proxied Requests

Host → View Requests

Notification Types

Host → View

View → Host

Union Types

Event Maps

Method Constants

Other Constants

Zod Schemas

Core Type Schemas

Initialization Schemas

Request / Result Schemas

Notification Schemas

Metadata Schemas

​Request / Result Types

​Initialization

​View → Host Requests

​Proxied Requests

​Host → View Requests

​Notification Types

​Host → View

​View → Host

​Union Types

​Event Maps

​Method Constants

​Other Constants

​Zod Schemas

​Core Type Schemas

​Initialization Schemas

​Request / Result Schemas

​Notification Schemas

​Metadata Schemas

Request / Result Types

Initialization

View → Host Requests

Proxied Requests

Host → View Requests

Notification Types

Host → View

View → Host

Union Types

Event Maps

Method Constants

Other Constants

Zod Schemas

Core Type Schemas

Initialization Schemas

Request / Result Schemas

Notification Schemas

Metadata Schemas