MCP Apps App Class - Client-Side Host Communication

MCP Apps SDK

import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";

Overview

The App class provides a framework-agnostic way to build interactive MCP Apps that run inside host applications. It extends ProtocolWithEvents (which itself extends the MCP SDK’s Protocol class) and handles the connection lifecycle, initialization handshake, and bidirectional communication with the host. The ProtocolWithEvents base class adds DOM-style addEventListener/removeEventListener support for composable, multi-listener event handling alongside the traditional on* setter properties.

Constructor

new App(appInfo, capabilities?, options?)

appInfo

Implementation

required

App identification: { name: string; version: string }.

capabilities

McpUiAppCapabilities

default:"{}"

Features this app provides. Set tools to expose app-side tools to the host. Set availableDisplayModes to declare supported display modes.

options

AppOptions

default:"{ autoResize: true }"

autoResize

boolean

default:"true"

Automatically report size changes to the host using ResizeObserver.

const app = new App(
  { name: "MyApp", version: "1.0.0" },
  { tools: { listChanged: true } },
  { autoResize: true },
);

connect()

Establishes connection with the host and performs the initialization handshake.

async connect(transport?: Transport, options?: RequestOptions): Promise<void>

Steps performed:

Connects the transport layer
Sends ui/initialize with app info and capabilities
Receives host capabilities and context
Sends ui/notifications/initialized (see Lifecycle)
Sets up auto-resize if enabled

If no transport is provided, defaults to new PostMessageTransport(window.parent, window.parent).

// Default transport (typical usage)
await app.connect();

// Custom transport
await app.connect(new PostMessageTransport(window.parent, window.parent));

Accessors

getHostCapabilities()

Returns the host’s capabilities from the initialization handshake. undefined before connection.

await app.connect();
if (app.getHostCapabilities()?.serverTools) {
  console.log("Host supports server tool calls");
}

getHostVersion()

Returns the host’s name and version. undefined before connection.

const { name, version } = app.getHostVersion() ?? {};
console.log(`Connected to ${name} v${version}`);

getHostContext()

Returns the current host context (theme, locale, display mode, etc.). Automatically updated when the host sends context change notifications.

const ctx = app.getHostContext();
if (ctx?.theme === "dark") {
  document.body.classList.add("dark-theme");
}

PostMessageTransport

The transport layer for iframe-to-parent communication using window.postMessage. In most cases you never need to use this directly — App.connect() creates one automatically when no transport is provided.

import { PostMessageTransport } from "@modelcontextprotocol/ext-apps";

new PostMessageTransport(eventTarget?, eventSource)

Method	Description
`start()`	Begin listening for messages
`send(message)`	Send a JSON-RPC message to the target
`close()`	Stop listening and clean up

Auto-Resize

By default, App monitors document.body and document.documentElement for size changes and sends ui/notifications/size-changed to the host. Disable with { autoResize: false }. In React, you can use the useAutoResize hook instead. For the full host sizing contract, including fixed vs flexible containerDimensions and display mode changes, see Layout and Display.

setupSizeChangedNotifications()

Manually start auto-resize reporting. Returns a cleanup function. Automatically called by connect() when autoResize: true.

const app = new App({ name: "MyApp", version: "1.0.0" }, {}, { autoResize: false });
await app.connect();

// Later, enable auto-resize manually
const cleanup = app.setupSizeChangedNotifications();
cleanup(); // Stop observing

sendSizeChanged()

Manually notify the host of a size change:

app.sendSizeChanged({ width: 400, height: 600 });

In React, the SDK’s useApp hook handles App creation and connection automatically. The sunpeak framework provides additional convenience hooks like useApp.

​Overview

​Constructor

​connect()

​Accessors

​getHostCapabilities()

​getHostVersion()

​getHostContext()

​PostMessageTransport

​Auto-Resize

​setupSizeChangedNotifications()

​sendSizeChanged()

Overview

Constructor

connect()

Accessors

getHostCapabilities()

getHostVersion()

getHostContext()

PostMessageTransport

Auto-Resize

setupSizeChangedNotifications()

sendSizeChanged()