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?)

Implementation

required

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

McpUiAppCapabilities

default:"{}"

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

AppOptions

default:"{ autoResize: true }"

boolean

default:"true"

Automatically report size changes to the host using ResizeObserver.

boolean

default:"false"

Throw when host-bound methods run before the initialization handshake completes. The default logs a warning. Throwing is planned to become the SDK default in a future release.

boolean

default:"false"

Allow schema parsing paths that require CSP unsafe-eval. Keep this disabled for normal MCP App Views.

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

Strict initialization checks

Host-bound methods such as callServerTool(), sendMessage(), and updateModelContext() must run after connect() completes. Calling them earlier can race the ui/initialize handshake and leave a strict Host waiting for a View that never becomes ready. Use strict: true during development to turn this ordering mistake into an immediate error:

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

app.ontoolresult = renderResult;
await app.connect();

// Host-bound methods are safe after connect() resolves.
await app.updateModelContext({
  content: [{ type: "text", text: "The View is ready." }],
});

CSP-safe schema parsing

MCP App Views run under a restrictive Content Security Policy. By default, the SDK configures Zod’s parser to avoid generated functions that require unsafe-eval. Keep allowUnsafeEval at its default false unless you control the Host CSP and have a measured reason to enable the faster JIT path. Setting it to true does not change the Host CSP, so parsing will still fail if the Host blocks unsafe-eval.

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));

For the difference between the core MCP handshake, the View handshake, the SDK package version, and appInfo.version, see Protocol Versions and Compatibility.

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

App

MCP

React

Server

Styling

Types

MCP Apps App Class - Client-Side Host Communication

Overview

Constructor

Strict initialization checks

CSP-safe schema parsing

connect()

Accessors

getHostCapabilities()

getHostVersion()

getHostContext()

PostMessageTransport

Auto-Resize

setupSizeChangedNotifications()

sendSizeChanged()

​Overview

​Constructor

​Strict initialization checks

​CSP-safe schema parsing

​connect()

​Accessors

​getHostCapabilities()

​getHostVersion()

​getHostContext()

​PostMessageTransport

​Auto-Resize

​setupSizeChangedNotifications()

​sendSizeChanged()

Overview

Constructor

Strict initialization checks

CSP-safe schema parsing

connect()

Accessors

getHostCapabilities()

getHostVersion()

getHostContext()

PostMessageTransport

Auto-Resize

setupSizeChangedNotifications()

sendSizeChanged()