MCP Apps Event Handlers - Host Events

MCP Apps SDK

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

Overview

The App class supports two patterns for handling host notifications and requests:

Setter properties (app.ontoolinput = ...) follow DOM-model replace semantics (like el.onclick). Assigning replaces any previous handler; assigning undefined clears it.
addEventListener (app.addEventListener("toolinput", ...)) supports multiple listeners and cleanup via removeEventListener. Preferred when you need composable handlers.

Both patterns are convenience wrappers around setNotificationHandler() and setRequestHandler() from the MCP SDK’s Protocol class. For making requests from the View to the host, see Requests.

Notification Handlers

ontoolinput

Called when the host sends complete tool arguments. This arrives after a tool call begins and before the tool result.

app.ontoolinput = (params) => {
  console.log("Tool arguments:", params.arguments);
};

Record<string, unknown>

Complete tool call arguments as key-value pairs.

ontoolinputpartial

Called as the host streams partial tool arguments during tool call initialization. Use for progressive rendering before complete input is available.

const codePreview = document.querySelector<HTMLPreElement>("#code-preview")!;

app.ontoolinputpartial = (params) => {
  codePreview.textContent = (params.arguments?.code as string) ?? "";
};

Record<string, unknown>

Partial tool arguments (healed JSON — incomplete objects may be truncated).

Partial arguments are “healed” JSON — the host closes unclosed brackets/braces to produce valid JSON. The last item in arrays or objects may be truncated. Use partial data only for preview UI, not for critical operations.

ontoolresult

Called when the host sends the result of a tool execution.

app.ontoolresult = (params) => {
  if (params.isError) {
    console.error("Tool failed:", params.content);
  } else {
    console.log("Tool output:", params.content);
    console.log("Structured data:", params.structuredContent);
  }
};

CallToolResult

Standard MCP tool execution result. Key fields:

Field	Type	Description
`content`	`ContentBlock[]`	Text content for model context
`structuredContent`	`unknown`	Any JSON value optimized for UI rendering
`isError`	`boolean`	Whether the tool returned an error
`_meta`	`object`	Optional protocol-level and server metadata

ontoolcancelled

Called when tool execution is cancelled (user action, timeout, classifier intervention).

app.ontoolcancelled = (params) => {
  console.log("Cancelled:", params.reason);
};

string

Optional reason for the cancellation.

onhostcontextchanged

Called when the host context changes (theme toggle, resize, locale change, etc.). Params are automatically merged into the internal context before the callback — getHostContext() returns updated values.

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) {
    document.body.classList.toggle("dark", ctx.theme === "dark");
  }
  if (ctx.displayMode) {
    container.classList.toggle("fullscreen", ctx.displayMode === "fullscreen");
  }
  if (ctx.availableDisplayModes) {
    fullscreenBtn.style.display =
      ctx.availableDisplayModes.includes("fullscreen") ? "block" : "none";
  }
};

McpUiHostContext

Partial context update containing only changed fields. See Core Types for the full McpUiHostContext structure.

Request Handlers

onteardown

Called when the host requests graceful shutdown before unmounting the iframe. Return {} (or a promise resolving to {}) when ready.

app.onteardown = async () => {
  await saveState();
  closeConnections();
  return {};
};

oncalltool

Handle tool calls from the host directed at this app. Requires declaring tools capability in the constructor. For the full picture of registering tools, see App Tools.

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

app.oncalltool = async (params) => {
  if (params.name === "get-selection") {
    return { content: [{ type: "text", text: selectedText }] };
  }
  throw new Error(`Unknown tool: ${params.name}`);
};

string

Name of the tool being called.

Record<string, unknown>

Tool arguments.

onlisttools

Return the list of tools this app provides. Requires declaring tools capability.

app.onlisttools = async () => {
  return {
    tools: [
      { name: "get-selection", inputSchema: { type: "object" } },
      { name: "format-text", inputSchema: { type: "object" } },
    ],
  };
};

Use Method-keyed Handlers for Custom Messages

Use the typed setters and addEventListener() for standard MCP App events. If you control both the View and Host and need a custom protocol message, SDK 2.0 keys the underlying handlers by method name:

import { z } from "zod";

const SelectionChangedParams = z.object({ itemId: z.string() });

app.setNotificationHandler(
  "example/selection-changed",
  { params: SelectionChangedParams },
  (params) => {
    console.log("Selected item:", params.itemId);
  },
);

The three-argument form validates custom notification params before calling the handler. Custom requests use the same method-keyed shape with setRequestHandler(method, { params, result? }, handler).

Custom methods are outside the MCP Apps specification. A normal Host will not send or handle them, so use this API only when you own the Host integration. Do not replace built-in progress, cancellation, or ui/* handlers. See Update Custom Protocol Handlers when migrating 1.x code.

Register event handlers in the onAppCreated callback of useApp to ensure they’re set before the handshake. The sunpeak framework provides convenience hooks: useToolData, useTeardown, and useAppTools.

Overview

App

MCP

React

Server

Styling

Types

MCP Apps Event Handlers - Host Events

Overview

Notification Handlers

ontoolinput

ontoolinputpartial

ontoolresult

ontoolcancelled

onhostcontextchanged

Request Handlers

onteardown

oncalltool

onlisttools

Use Method-keyed Handlers for Custom Messages

​Overview

​Notification Handlers

​Request Handlers

​Use Method-keyed Handlers for Custom Messages

Overview

Notification Handlers

Request Handlers

Use Method-keyed Handlers for Custom Messages