> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Apps Protocol Reference - Types & Schemas

> Complete MCP Apps protocol reference: request and result types, notification types, method constants, union types (AppRequest, AppNotification, AppResult), and Zod validation schemas.

<Badge color="green">MCP Apps SDK</Badge>

<Note>This documentation covers MCP Apps SDK v1.7.4 (`@modelcontextprotocol/ext-apps`).</Note>

```ts theme={null}
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`](/mcp-apps/app/requests/call-server-tool).              |
| `CallToolResult`                                       | —                        | Server → View | Tool execution result.                                                                                |
| `ReadResourceRequest`                                  | `resources/read`         | View → Server | Read a server resource. Used by [`readServerResource`](/mcp-apps/app/requests/read-server-resource).  |
| `ReadResourceResult`                                   | —                        | Server → View | Resource contents.                                                                                    |
| `ListResourcesRequest`                                 | `resources/list`         | View → Server | List server resources. Used by [`listServerResources`](/mcp-apps/app/requests/list-server-resources). |
| `ListResourcesResult`                                  | —                        | Server → View | Resource list with optional cursor.                                                                   |
| `CreateMessageRequest`                                 | `sampling/createMessage` | View → Host   | LLM completion. Used by [`createSamplingMessage`](/mcp-apps/app/requests/create-sampling-message).    |
| `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`](/mcp-apps/app/requests#requestteardown).                                                         |
| `LoggingMessageNotification`       | `notifications/message`             | Diagnostic log message. Sent by [`sendLog`](/mcp-apps/app/requests/send-log).                                                                                   |
| `ToolListChangedNotification`      | `notifications/tools/list_changed`  | App-side tool list changed. Sent by [`sendToolListChanged`](/mcp-apps/app/requests#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`                                                                                                                                                                                                                                                                                                                                  |

```ts theme={null}
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`.

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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               |