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
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
Protected_Protected accessor for a registered request handler. Used by role
classes that dispatch synthesized requests through the same stored
handler chain (e.g. the Client fulfilling an embedded multi-round-trip
input request).
Protected_Transport-close hook. Subclass overrides MUST call super._onclose()
after their own cleanup — base teardown (response-handler settlement,
timeout clearing, in-flight request abort) does not run otherwise.
Protected_Inbound-notification dispatch. Subclass overrides MUST delegate
unmatched traffic to super._onnotification(rawNotification, extra) —
an override that consumes only what it owns and falls through to base
dispatch for everything else.
Optionalextra: MessageExtraInfoProtected_Inbound-response dispatch. Subclass overrides MUST delegate unmatched
traffic to super._onresponse(response) — an override that consumes
only what it owns and falls through to base dispatch for everything
else.
Protected_The per-request _meta envelope this instance attaches to every outgoing
request and notification, when one applies. The base implementation
returns undefined (no envelope — the 2025-era posture, so legacy-era
outbound traffic is byte-identical to a build without this seam).
Client overrides it on a connection that negotiated a modern (2026-07-28+)
era to return the reserved protocol-version / client-info /
client-capabilities keys. User-supplied _meta keys take precedence over
the auto-attached ones.
Protected_Hook for subclasses to supply the implementation identity the 2026-era
encode seam stamps into outbound result _meta under
io.modelcontextprotocol/serverInfo (spec PR #3002: servers SHOULD
identify themselves on every response). The default is undefined — no
stamp. Only Server overrides this: the key identifies the software
producing a response, and the 2025-era codec never stamps anything
regardless (the never-stamp guarantee).
Protected_Sends a request and waits for a response, using the provided schema for validation instead of the era registry's method-keyed entry.
This is the internal implementation used by SDK methods whose result
schema cannot be expressed as a method-keyed registry entry — the one
surviving case is server.createMessage, whose result schema depends
on the REQUEST params (tools vs no tools) — and by callers passing
explicit compatibility schemas. Spec methods are still era-gated here:
an explicit schema never smuggles a deleted method onto the wire.
Optionaloptions: RequestOptionsProtected_Extension point for non-complete decoded results in the response
funnel: a result the wire codec discriminated into a kind other than
'complete' or 'invalid' is handed here for the role class to
resolve. The base default surfaces it as a typed
SdkErrorCode.UnsupportedResultType error (no retry).
Intended consumers (named so the seam stays accountable):
Client's multi-round-trip auto-fulfilment engine, which fulfils
'input_required' results through the registered
elicitation/sampling/roots handlers and retries via flow.retry;subscriptions/listen, when the spec defines one.Server instances never receive input_required responses on their
outbound legs and leave the base behavior in place.
Protected_Drop consult for inbound messages whose transport did not classify them at the edge — long-lived channels such as stdio, where a role class may need to decline traffic the negotiated era has no answer for (the client-side inbound-request drop on modern-era connections: the 2026-07-28 era has no server→client request channel, and on stdio the client must never write JSON-RPC responses).
Consulted ONLY when the transport supplied no
MessageExtraInfo.classification: edge-classified traffic
never reaches the hook. Returning 'drop' discards the message without
writing any response (requests are surfaced via onerror). The base
implementation returns undefined: unclassified traffic keeps today's
dispatch path unchanged. Era selection never happens here — era is
instance state, owned by the serving entry that constructed and
connected the instance.
Protected_Protected accessor for the instance's negotiated wire codec, for role
classes (Client/Server/McpServer) routing era-dependent behavior
through the codec's function-only surface — samplingResultVariant,
outboundEnvelope, projectCallToolResult — instead of branching on
the protocol version themselves.
Protected_Hook for subclasses to wrap a registered request handler with role-specific
validation or behavior (e.g. Server validates tools/call results, Client
validates elicitation/create mode and result). Runs for both the 2-arg and
3-arg registration paths. The default implementation is identity.
Subclasses overriding this hook avoid redeclaring setRequestHandler's overload set.
Asserts that a request handler has not already been set for the given method, in preparation for a new one being automatically installed.
ProtectedassertInternalVerify that the host supports the capability required for the given request method.
ProtectedassertInternalVerify that the app supports the capability required for the given notification method.
ProtectedassertInternalVerify that the app declared the capability required for the given request method.
ProtectedbuildInternalCall 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);
}
Closes 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 an LLM completion from the host (standard MCP sampling/createMessage).
Enables the app to use the host's model connection for completions. The host
has full discretion over which model to select and MAY modify or reject the
request (human-in-the-loop). Check getHostCapabilities()?.sampling
before calling — hosts without this capability will reject the request.
This method reuses the stock MCP CreateMessageRequest shape. When params.tools
is provided, the result is parsed with the extended schema that permits
stopReason: "toolUse" and array content containing tool_use blocks.
Standard MCP CreateMessageRequest params (messages, maxTokens,
systemPrompt, temperature, modelPreferences, tools, toolChoice, etc.)
Optionaloptions: RequestOptionsRequest options (timeout, abort signal)
CreateMessageResult (single content block) or CreateMessageResultWithTools
(array content, may include tool_use blocks) depending on whether tools was set
const result = await app.createSamplingMessage({
messages: [
{
role: "user",
content: { type: "text", text: "Summarize this in one line." },
},
],
maxTokens: 100,
});
console.log(result.content);
if (!app.getHostCapabilities()?.sampling?.tools) return;
const result = await app.createSamplingMessage({
messages,
maxTokens: 1024,
tools: [
{
name: "get_weather",
description: "Get the current weather",
inputSchema: {
type: "object",
properties: { city: { type: "string" } },
},
},
],
});
if (result.stopReason === "toolUse") {
// result.content may be an array containing tool_use blocks
}
Request an LLM completion from the host (standard MCP sampling/createMessage).
Enables the app to use the host's model connection for completions. The host
has full discretion over which model to select and MAY modify or reject the
request (human-in-the-loop). Check getHostCapabilities()?.sampling
before calling — hosts without this capability will reject the request.
This method reuses the stock MCP CreateMessageRequest shape. When params.tools
is provided, the result is parsed with the extended schema that permits
stopReason: "toolUse" and array content containing tool_use blocks.
Standard MCP CreateMessageRequest params (messages, maxTokens,
systemPrompt, temperature, modelPreferences, tools, toolChoice, etc.)
Optionaloptions: RequestOptionsRequest options (timeout, abort signal)
CreateMessageResult (single content block) or CreateMessageResultWithTools
(array content, may include tool_use blocks) depending on whether tools was set
const result = await app.createSamplingMessage({
messages: [
{
role: "user",
content: { type: "text", text: "Summarize this in one line." },
},
],
maxTokens: 100,
});
console.log(result.content);
if (!app.getHostCapabilities()?.sampling?.tools) return;
const result = await app.createSamplingMessage({
messages,
maxTokens: 1024,
tools: [
{
name: "get_weather",
description: "Get the current weather",
inputSchema: {
type: "object",
properties: { city: { type: "string" } },
},
},
],
});
if (result.stopReason === "toolUse") {
// result.content may be an array containing tool_use blocks
}
Request 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
List 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
Emits a notification, which is a one-way message that does not expect a response.
Optionaloptions: NotificationOptionsRequest 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
Sends a request and waits for a response.
For spec methods the result schema is resolved automatically from the method name
and the return type is method-keyed. For custom (non-spec) methods, pass a
resultSchema as the second argument; the response is validated against it and
the return type is inferred from the schema.
Do not use this method to emit notifications! Use notification() instead.
Optionaloptions: RequestOptionsSends a request and waits for a response.
For spec methods the result schema is resolved automatically from the method name
and the return type is method-keyed. For custom (non-spec) methods, pass a
resultSchema as the second argument; the response is validated against it and
the return type is inferred from the schema.
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 availableDisplayModesRequest 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 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",
},
],
});
}
ProtectedwarnProtected Optional_The protocol version negotiated for the current connection (undefined
before negotiation completes), which determines the wire era this
instance speaks. Set by the SDK's negotiation and initialize paths
(Client.connect, Server._oninitialize).
Protected_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.
Removes the notification handler for the given method.
Removes the request handler for the given method.
ProtectedreplaceRegister a request handler with replace semantics, bypassing the
double-set protection of setRequestHandler.
Used by the on* request-handler setters.
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.
For spec methods, pass (method, handler); the request is parsed with the spec
schema and the handler receives the typed Request. For custom (non-spec)
methods, pass (method, schemas, handler); params are validated against
schemas.params and the handler receives the parsed params object directly.
Supplying schemas.result types the handler's return value.
const SearchParams = z.object({ query: z.string(), limit: z.number().optional() });
const SearchResult = z.object({ hits: z.array(z.string()) });
protocol.setRequestHandler('acme/search', { params: SearchParams, result: SearchResult }, async (params, _ctx) => {
return { hits: [`result for ${params.query}`] };
});
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.
For spec methods, pass (method, handler); the request is parsed with the spec
schema and the handler receives the typed Request. For custom (non-spec)
methods, pass (method, schemas, handler); params are validated against
schemas.params and the handler receives the parsed params object directly.
Supplying schemas.result types the handler's return value.
const SearchParams = z.object({ query: z.string(), limit: z.number().optional() });
const SearchResult = z.object({ hits: z.array(z.string()) });
protocol.setRequestHandler('acme/search', { params: SearchParams, result: SearchResult }, async (params, _ctx) => {
return { hits: [`result for ${params.query}`] };
});
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 request handler. Throws if a handler for the same method has
already been registered — use the on* setter for replace semantics.
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 base MCP SDK's publicProtocolclass, composes an EventDispatcher, and adds the Apps handshake, lifecycle, and high-level APIs.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 handshakeProtocol and event methods
From the base MCP SDK's
Protocol,Appprovides:setRequestHandler()- Register handlers for requests from hostsetNotificationHandler()- Register handlers for notifications from hostFrom its composed EventDispatcher,
Appalso provides:addEventListener()- Append a listener for a notification event (multi-listener)removeEventListener()- Remove a previously added listenerNotification 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