Convenience handler for host context changes (theme, locale, etc.).
Set this property to register a handler that will be called when the host's context changes, such as theme switching (light/dark), locale changes, or other environmental updates. Apps should respond by updating their UI accordingly.
Assigning replaces the previous handler; assigning undefined clears it.
Use addEventListener to attach multiple listeners
without replacing.
Notification params are automatically merged into the internal host context
via onEventDispatch before any handler or listener
fires. This means getHostContext will return the
updated values even before your callback runs.
Register handlers before calling connect to avoid missing notifications.
app.onhostcontextchanged = (ctx) => {
if (ctx.theme === "dark") {
document.body.classList.add("dark-theme");
} else {
document.body.classList.remove("dark-theme");
}
};
Use addEventListener("hostcontextchanged", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
McpUiHostContextChangedNotification for the notification structureMcpUiHostContext for the full context structureConvenience handler for receiving tool cancellation notifications from the host.
Set this property to register a handler that will be called when the host notifies that tool execution was cancelled. This can occur for various reasons including user action, sampling error, classifier intervention, or other interruptions. Apps should update their state and display appropriate feedback.
Assigning replaces the previous handler; assigning undefined clears it.
Use addEventListener to attach multiple listeners
without replacing.
Register handlers before calling connect to avoid missing notifications.
app.ontoolcancelled = (params) => {
console.log("Tool cancelled:", params.reason);
// Update your UI to show cancellation state
};
Use addEventListener("toolcancelled", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
McpUiToolCancelledNotification for the notification structureontoolresult for successful tool completionConvenience handler for receiving complete tool input from the host.
Set this property to register a handler that will be called when the host sends a tool's complete arguments. This is sent after a tool call begins and before the tool result is available.
Assigning replaces the previous handler; assigning undefined clears it.
Use addEventListener to attach multiple listeners
without replacing.
Register handlers before calling connect to avoid missing notifications.
// Register before connecting to ensure no notifications are missed
app.ontoolinput = (params) => {
console.log("Tool:", params.arguments);
// Update your UI with the tool arguments
};
await app.connect();
Use addEventListener("toolinput", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
McpUiToolInputNotification for the notification structure
Convenience handler for receiving streaming partial tool input from the host.
Set this property to register a handler that will be called as the host streams partial tool arguments during tool call initialization. This enables progressive rendering of tool arguments before they're complete.
Important: Partial arguments are "healed" JSON — the host closes unclosed brackets/braces to produce valid JSON. This means objects may be incomplete (e.g., the last item in an array may be truncated). Use partial data only for preview UI, not for critical operations.
Assigning replaces the previous handler; assigning undefined clears it.
Use addEventListener to attach multiple listeners
without replacing.
Register handlers before calling connect to avoid missing notifications.
const codePreview = document.querySelector<HTMLPreElement>("#code-preview")!;
const canvas = document.querySelector<HTMLCanvasElement>("#canvas")!;
app.ontoolinputpartial = (params) => {
codePreview.textContent = (params.arguments?.code as string) ?? "";
codePreview.style.display = "block";
canvas.style.display = "none";
};
app.ontoolinput = (params) => {
codePreview.style.display = "none";
canvas.style.display = "block";
render(params.arguments?.code as string);
};
Use addEventListener("toolinputpartial", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
McpUiToolInputPartialNotification for the notification structureontoolinput for the complete tool input handlerConvenience handler for receiving tool execution results from the host.
Set this property to register a handler that will be called when the host sends the result of a tool execution. This is sent after the tool completes on the MCP server, allowing your app to display the results or update its state.
Assigning replaces the previous handler; assigning undefined clears it.
Use addEventListener to attach multiple listeners
without replacing.
Register handlers before calling connect to avoid missing notifications.
app.ontoolresult = (params) => {
if (params.isError) {
console.error("Tool execution failed:", params.content);
} else if (params.content) {
console.log("Tool output:", params.content);
}
};
Use addEventListener("toolresult", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
McpUiToolResultNotification for the notification structureontoolinput for the initial tool input handlerCreate a new MCP App instance.
App identification (name and version)
Features and capabilities this app provides
Configuration options including autoResize behavior
Add a listener for a notification event.
Unlike the singular on* handler, calling this multiple times appends
listeners rather than replacing them. All registered listeners fire in
insertion order after the on* handler when the notification arrives.
Registration is lazy: the first call (for a given event, from either
this method or the on* setter) registers a dispatcher with the base
Protocol.
Asserts that a request handler has not already been set for the given method, in preparation for a new one being automatically installed.
InternalVerify that the host supports the capability required for the given request method.
InternalVerify that the app supports the capability required for the given notification method.
InternalVerify that the app declared the capability required for the given request method.
ProtectedassertInternalVerify that task creation is supported for the given request method.
ProtectedassertInternalVerify that task handler is supported for the given method.
Call a tool on the originating MCP server (proxied through the host).
Apps can call tools to fetch fresh data or trigger server-side actions. The host proxies the request to the actual MCP server and returns the result.
Tool name and arguments
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Tool execution result
If the host rejects the request
Note: Tool-level execution errors are returned in the result with isError: true
rather than throwing exceptions. Always check result.isError to distinguish
between transport failures (thrown) and tool execution failures (returned).
try {
const result = await app.callServerTool({
name: "get_weather",
arguments: { location: "Tokyo" },
});
if (result.isError) {
console.error("Tool returned error:", result.content);
} else {
console.log(result.content);
}
} catch (error) {
console.error("Tool call failed:", error);
}
ProtectedcancelExperimentalCancels a specific task.
Use client.experimental.tasks.cancelTask() to access this method.
Optionaloptions: RequestOptionsCloses the connection.
Establish connection with the host and perform initialization handshake.
This method performs the following steps:
ui/initialize request with app info and capabilitiesui/notifications/initialized notificationsetupSizeChangedNotifications if enabled (default)If initialization fails, the connection is automatically closed and an error is thrown.
Transport layer (typically PostMessageTransport)
Optionaloptions: RequestOptionsRequest options for the initialize request
const app = new App({ name: "MyApp", version: "1.0.0" }, {});
try {
await app.connect(new PostMessageTransport(window.parent, window.parent));
console.log("Connected successfully!");
} catch (error) {
console.error("Failed to connect:", error);
}
McpUiInitializeRequest for the initialization request structureMcpUiInitializedNotification for the initialized notificationPostMessageTransport for the typical transport implementationRequest the host to download a file.
Since MCP Apps run in sandboxed iframes where direct downloads are blocked, this provides a host-mediated mechanism for file exports. The host will typically show a confirmation dialog before initiating the download.
Uses standard MCP resource types: EmbeddedResource for inline content
and ResourceLink for content the host can fetch directly.
Resource contents to download
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Result with isError: true if the host denied the request (e.g., user cancelled)
const data = JSON.stringify({ items: selectedItems }, null, 2);
const { isError } = await app.downloadFile({
contents: [{
type: "resource",
resource: {
uri: "file:///export.json",
mimeType: "application/json",
text: data,
},
}],
});
if (isError) {
console.warn("Download denied or cancelled");
}
const { isError } = await app.downloadFile({
contents: [{
type: "resource",
resource: {
uri: "file:///image.png",
mimeType: "image/png",
blob: base64EncodedPng,
},
}],
});
const { isError } = await app.downloadFile({
contents: [{
type: "resource_link",
uri: "https://api.example.com/reports/q4.pdf",
name: "Q4 Report",
mimeType: "application/pdf",
}],
});
McpUiDownloadFileRequest for request structureMcpUiDownloadFileResult for result structureProtectedgetGet the host's capabilities discovered during initialization.
Returns the capabilities that the host advertised during the
connect handshake. Returns undefined if called before
connection is established.
Host capabilities, or undefined if not yet connected
await app.connect();
if (app.getHostCapabilities()?.serverTools) {
console.log("Host supports server tool calls");
}
connect for the initialization handshakeMcpUiHostCapabilities for the capabilities structureGet the host context discovered during initialization.
Returns the host context that was provided in the initialization response,
including tool info, theme, locale, and other environment details.
This context is automatically updated when the host sends
ui/notifications/host-context-changed notifications.
Returns undefined if called before connection is established.
Host context, or undefined if not yet connected
await app.connect(transport);
const context = app.getHostContext();
if (context?.theme === "dark") {
document.body.classList.add("dark-theme");
}
if (context?.toolInfo) {
console.log("Tool:", context.toolInfo.tool.name);
}
connect for the initialization handshakeonhostcontextchanged for context change notificationsMcpUiHostContext for the context structureGet the host's implementation info discovered during initialization.
Returns the host's name and version as advertised during the
connect handshake. Returns undefined if called before
connection is established.
Host implementation info, or undefined if not yet connected
await app.connect(transport);
const { name, version } = app.getHostVersion() ?? {};
console.log(`Connected to ${name} v${version}`);
connect for the initialization handshake
ProtectedgetExperimentalGets the current status of a task.
Use client.experimental.tasks.getTask() to access this method.
Optionaloptions: RequestOptionsProtectedgetExperimentalRetrieves the result of a completed task.
Use client.experimental.tasks.getTaskResult() to access this method.
Optionaloptions: RequestOptionsList available resources from the originating MCP server (proxied through the host).
Apps can list resources to discover what content is available on the MCP server. This enables dynamic resource discovery and building resource browsers or pickers. The host proxies the request to the actual MCP server and returns the resource list.
Results may be paginated using the cursor parameter for servers with many resources.
Optionalparams: {Optional parameters (omit for all resources, or { cursor } for pagination)
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
List of resources with their URIs, names, descriptions, mimeTypes, and optional pagination cursor
try {
const result = await app.listServerResources();
const videoResources = result.resources.filter((r) =>
r.mimeType?.startsWith("video/"),
);
videoResources.forEach((resource) => {
const option = document.createElement("option");
option.value = resource.uri;
option.textContent = resource.description || resource.name;
selectElement.appendChild(option);
});
} catch (error) {
console.error("Failed to list resources:", error);
}
readServerResource to read a specific resource
ProtectedlistExperimentalLists tasks, optionally starting from a pagination cursor.
Use client.experimental.tasks.listTasks() to access this method.
Optionalparams: { cursor?: string }Optionaloptions: RequestOptionsEmits a notification, which is a one-way message that does not expect a response.
Optionaloptions: NotificationOptionsProtectedonRequest the host to open an external URL in the default browser.
The host may deny this request based on user preferences or security policy.
Apps should handle rejection gracefully by checking result.isError.
URL to open
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Result with isError: true if the host denied the request (e.g., blocked domain, user cancelled)
const { isError } = await app.openLink({ url: "https://docs.example.com" });
if (isError) {
// Host denied the request (e.g., blocked domain, user cancelled)
// Optionally show fallback: display URL for manual copy
console.warn("Link request denied");
}
McpUiOpenLinkRequest for request structureMcpUiOpenLinkResult for result structureRead a resource from the originating MCP server (proxied through the host).
Apps can read resources to access files, data, or other content provided by
the MCP server. Resources are identified by URI (e.g., file:///path/to/file
or custom schemes like videos://bunny-1mb). The host proxies the request to
the actual MCP server and returns the resource content.
Resource URI to read
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Resource content with URI, name, description, mimeType, and contents array
try {
const result = await app.readServerResource({
uri: "videos://bunny-1mb",
});
const content = result.contents[0];
if (content && "blob" in content) {
const binary = Uint8Array.from(atob(content.blob), (c) =>
c.charCodeAt(0),
);
const url = URL.createObjectURL(
new Blob([binary], { type: content.mimeType || "video/mp4" }),
);
videoElement.src = url;
videoElement.play();
}
} catch (error) {
console.error("Failed to read resource:", error);
}
listServerResources to discover available resources
Removes the notification handler for the given method.
Removes the request handler for the given method.
Sends a request and waits for a response.
Do not use this method to emit notifications! Use notification() instead.
Optionaloptions: RequestOptionsRequest a change to the display mode.
Requests the host to change the UI container to the specified display mode
(e.g., "inline", "fullscreen", "pip"). The host will respond with the actual
display mode that was set, which may differ from the requested mode if
the requested mode is not available (check availableDisplayModes in host context).
The display mode being requested
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Result containing the actual display mode that was set
const container = document.getElementById("main")!;
const ctx = app.getHostContext();
const newMode = ctx?.displayMode === "inline" ? "fullscreen" : "inline";
if (ctx?.availableDisplayModes?.includes(newMode)) {
const result = await app.requestDisplayMode({ mode: newMode });
container.classList.toggle("fullscreen", result.mode === "fullscreen");
}
McpUiRequestDisplayModeRequest for request structureMcpUiHostContext for checking availableDisplayModesProtectedrequestExperimentalSends a request and returns an AsyncGenerator that yields response messages. The generator is guaranteed to end with either a 'result' or 'error' message.
Optionaloptions: RequestOptionsconst stream = protocol.requestStream(request, resultSchema, options);
for await (const message of stream) {
switch (message.type) {
case 'taskCreated':
console.log('Task created:', message.task.taskId);
break;
case 'taskStatus':
console.log('Task status:', message.task.status);
break;
case 'result':
console.log('Final result:', message.result);
break;
case 'error':
console.error('Error:', message.error);
break;
}
}
Use client.experimental.tasks.requestStream() to access this method.
Request the host to tear down this app.
Apps call this method to request that the host tear them down. The host
decides whether to proceed - if approved, the host will send
ui/resource-teardown to allow the app to perform gracefull termination before being
unmounted. This piggybacks on the existing teardown mechanism, ensuring
the app only needs a single shutdown procedure (via onteardown)
regardless of whether the teardown was initiated by the app or the host.
This is a fire-and-forget notification - no response is expected.
If the host approves, the app will receive a ui/resource-teardown
request via the onteardown handler to persist unsaved state.
Empty params object (reserved for future use)
Promise that resolves when the notification is sent
// User clicks "Done" button in the app
async function handleDoneClick() {
// Request the host to tear down the app
await app.requestTeardown();
// If host approves, onteardown handler will be called for termination
}
// Set up teardown handler (called for both app-initiated and host-initiated teardown)
app.onteardown = async () => {
await saveState();
closeConnections();
return {};
};
McpUiRequestTeardownNotification for notification structureonteardown for the graceful termination handlerSend log messages to the host for debugging and telemetry.
Logs are not added to the conversation but may be recorded by the host for debugging purposes.
Log level and message
Promise that resolves when the log notification is sent
Send a message to the host's chat interface.
Enables the app to add messages to the conversation thread. Useful for user-initiated messages or app-to-conversation communication.
Message role and content
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Result with optional isError flag indicating host rejection
try {
const result = await app.sendMessage({
role: "user",
content: [{ type: "text", text: "Show me details for item #42" }],
});
if (result.isError) {
console.error("Host rejected the message");
// Handle rejection appropriately for your app
}
} catch (error) {
console.error("Failed to send message:", error);
// Handle transport/protocol error
}
const markdown = `---
word-count: ${fullTranscript.split(/\s+/).length}
speaker-names: ${speakerNames.join(", ")}
---
${fullTranscript}`;
// Offload long transcript to model context
await app.updateModelContext({ content: [{ type: "text", text: markdown }] });
// Send brief trigger message
await app.sendMessage({
role: "user",
content: [{ type: "text", text: "Summarize the key points" }],
});
McpUiMessageRequest for request structure
Notify the host of UI size changes.
Apps can manually report size changes to help the host adjust the container.
If autoResize is enabled (default), this is called automatically.
New width and height in pixels
Optionalheight?: numberOptionalwidth?: numberPromise that resolves when the notification is sent
McpUiSizeChangedNotification for notification structure
ProtectedsetSet or clear the singular on* handler for an event.
Replace semantics — like the DOM's el.onclick = fn. Assigning
undefined clears the handler without affecting addEventListener
listeners.
Set up automatic size change notifications using ResizeObserver.
Observes both document.documentElement and document.body for size changes
and automatically sends ui/notifications/size-changed notifications to the host.
The notifications are debounced using requestAnimationFrame to avoid duplicates.
Note: This method is automatically called by connect() if the autoResize
option is true (default). You typically don't need to call this manually unless
you disabled autoResize and want to enable it later.
Cleanup function to disconnect the observer
Update the host's model context with app state.
Context updates are intended to be available to the model in future
turns, without triggering an immediate model response (unlike sendMessage).
The host will typically defer sending the context to the model until the
next user message — either from the actual user or via sendMessage. Only
the last update is sent; each call overwrites any previous context.
Context content and/or structured content
Optionalcontent?: ContentBlock[]OptionalstructuredContent?: Record<string, unknown>Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Promise that resolves when the context update is acknowledged
const markdown = `---
item-count: ${itemList.length}
total-cost: ${totalCost}
currency: ${currency}
---
User is viewing their shopping cart with ${itemList.length} items selected:
${itemList.map((item) => `- ${item}`).join("\n")}`;
await app.updateModelContext({
content: [{ type: "text", text: markdown }],
});
try {
const _stream = await navigator.mediaDevices.getUserMedia({ audio: true });
// ... use _stream for transcription
} catch (err) {
// Inform the model that the app is in a degraded state
await app.updateModelContext({
content: [
{
type: "text",
text: "Error: transcription unavailable",
},
],
});
}
ProtectedwarnWarn if a request handler on* setter is replacing a previously-set
handler. Call from each request setter before updating the backing field.
Protected ReadonlyeventEvent name → notification schema. Subclasses populate this so that the event system can lazily register a dispatcher with the correct schema on first use.
OptionalfallbackA handler to invoke for any notification types that do not have their own handler installed.
OptionalfallbackA handler to invoke for any request types that do not have their own handler installed.
OptionaloncloseCallback for when the connection is closed for any reason.
This is invoked when close() is called as well.
OptionalonerrorCallback for when an error occurs.
Note that errors are not necessarily fatal; they are used for reporting any kind of exceptional condition out of band.
ProtectedreplaceReplace a request handler, bypassing double-set protection. Used by
on* request-handler setters that need replace semantics.
Registers a handler to invoke when this protocol object receives a request with the given method.
Note that this will replace any previous request handler for the same method.
Request the host to open an external URL in the default browser.
The host may deny this request based on user preferences or security policy.
Apps should handle rejection gracefully by checking result.isError.
URL to open
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Result with isError: true if the host denied the request (e.g., blocked domain, user cancelled)
const { isError } = await app.openLink({ url: "https://docs.example.com" });
if (isError) {
// Host denied the request (e.g., blocked domain, user cancelled)
// Optionally show fallback: display URL for manual copy
console.warn("Link request denied");
}
McpUiOpenLinkRequest for request structureMcpUiOpenLinkResult for result structureUse openLink instead
Registers a notification handler. Throws if a handler for the same
method has already been registered — use the on* setter (replace
semantics) or addEventListener (multi-listener) for mapped events.
Registers a handler to invoke when this protocol object receives a notification with the given method.
Note that this will replace any previous notification handler for the same method.
Registers a request handler. Throws if a handler for the same method
has already been registered — use the on* setter (replace semantics)
or addEventListener (multi-listener) for notification events.
Registers a handler to invoke when this protocol object receives a request with the given method.
Note that this will replace any previous request handler for the same method.
Main class for MCP Apps to communicate with their host.
The
Appclass provides a framework-agnostic way to build interactive MCP Apps that run inside host applications. It extends the MCP SDK'sProtocolclass and handles the connection lifecycle, initialization handshake, and bidirectional communication with the host.Architecture
Views (Apps) act as MCP clients connecting to the host via
PostMessageTransport. The host proxies requests to the actual MCP server and forwards responses back to the App.Lifecycle
connect()to establish transport and perform handshakeInherited Methods
As a subclass of ProtocolWithEvents
ProtocolWithEvents,Appinherits:setRequestHandler()- Register handlers for requests from hostsetNotificationHandler()- Register handlers for notifications from hostaddEventListener()- Append a listener for a notification event (multi-listener)removeEventListener()- Remove a previously added listenerSee
ProtocolWithEvents
ProtocolWithEventsfor the DOM-model event systemNotification Setters (DOM-model
on*handlers)For common notifications, the
Appclass provides getter/setter properties that follow DOM-model replace semantics (likeel.onclick):ontoolinput- Complete tool arguments from hostontoolinputpartial- Streaming partial tool argumentsontoolresult- Tool execution resultsontoolcancelled- Tool execution was cancelled by user or hostonhostcontextchanged- Host context changes (theme, locale, etc.)Assigning replaces the previous handler; assigning
undefinedclears it. UseaddEventListenerto attach multiple listeners without replacing.Example: Basic usage with PostMessageTransport