MCP Apps onteardown - Graceful Shutdown Handler

MCP Apps SDK

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

Overview

onteardown is a request handler called when the host is about to unmount the iframe and wants the app to shut down gracefully. This is your opportunity to save unsaved state, close open connections, flush analytics, or perform any other cleanup before the View is destroyed. Because this is a request (not a notification), the host waits for your response before proceeding. Return {} (or a promise resolving to {}) to signal that cleanup is complete. If the handler throws or the promise rejects, the host may force-close the iframe.

Signature

app.onteardown = () => {} | Promise<{}>;

Parameters

This handler receives no parameters.

Returns

Return {} or a Promise<{}> to indicate that shutdown is complete.

Usage

Save state before shutdown

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

await app.connect();

Flush pending work

app.onteardown = async () => {
  await Promise.all([
    analytics.flush(),
    pendingUploads.waitForCompletion(),
    database.close(),
  ]);
  return {};
};

await app.connect();

Synchronous cleanup

If your cleanup is synchronous, you can return {} directly:

app.onteardown = () => {
  clearInterval(pollingTimer);
  eventSource.close();
  return {};
};

await app.connect();

The host may impose a timeout on the teardown request. Avoid long-running operations — save critical state quickly and let non-critical work fail gracefully.

Event Handlers overview — all notification and request handlers
useTeardown — sunpeak React convenience hook
Lifecycle — connection, initialization, and shutdown flow

​Overview

​Signature

​Parameters

​Returns

​Usage

​Save state before shutdown

​Flush pending work

​Synchronous cleanup

​Related

Overview

Signature

Parameters

Returns

Usage

Save state before shutdown

Flush pending work

Synchronous cleanup

Related