Create a new AppBridge instance.
MCP client connected to the server, or null. When provided,
connect will automatically set up forwarding of MCP requests/notifications
between the View and the server. When null, you must register handlers
manually using the oncalltool, onlistresources, etc. setters.
Host application identification (name and version)
Features and capabilities the host supports
Optionaloptions: HostOptionsConfiguration options (inherited from Protocol)
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.
OptionalonpingOptional handler for ping requests from the view.
The View can send standard MCP ping requests to verify the connection
is alive. The AppBridge automatically responds with an empty object, but this
handler allows the host to observe or log ping activity.
Unlike the other handlers which use setters, this is a direct property assignment. It is optional; if not set, pings are still handled automatically.
Empty params object from the ping request
Request metadata (abort signal, session info)
Request graceful shutdown of the view.
The host MUST send this request before tearing down the UI resource (before unmounting the iframe). This gives the view an opportunity to save state, cancel pending operations, or show confirmation dialogs.
The host SHOULD wait for the response before unmounting to prevent data loss.
Empty params object
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Promise resolving when view confirms readiness for teardown
Use teardownResource instead
Register a handler for tool call requests from the view.
The view sends tools/call requests to execute MCP server tools. This
handler allows the host to intercept and process these requests, typically
by forwarding them to the MCP server.
Handler that receives tool call params and returns a
CallToolResult
params - Tool call parameters (name and arguments)extra - Request metadata (abort signal, session info)Register a handler for file download requests from the View.
The View sends ui/download-file requests when the user wants to
download a file. The params contain an array of MCP resource content
items — either EmbeddedResource (inline data) or ResourceLink
(URI the host can fetch). The host should show a confirmation dialog
and then trigger the download.
Handler that receives download params and returns a result
params.contents - Array of EmbeddedResource or ResourceLink itemsextra - Request metadata (abort signal, session info)Promise<McpUiDownloadFileResult> with optional isError flagbridge.ondownloadfile = async ({ contents }, extra) => {
for (const item of contents) {
if (item.type === "resource") {
// EmbeddedResource — inline content
const res = item.resource;
const blob = res.blob
? new Blob([Uint8Array.from(atob(res.blob), c => c.charCodeAt(0))], { type: res.mimeType })
: new Blob([res.text ?? ""], { type: res.mimeType });
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = res.uri.split("/").pop() ?? "download";
link.click();
URL.revokeObjectURL(url);
} else if (item.type === "resource_link") {
// ResourceLink — host fetches or opens directly
window.open(item.uri, "_blank");
}
}
return {};
};
McpUiDownloadFileRequest for the request typeMcpUiDownloadFileResult for the result typeCalled when the view completes initialization.
Set this callback to be notified when the view has finished its initialization handshake and is ready to receive tool input and other data.
bridge.oninitialized = () => {
console.log("View ready");
bridge.sendToolInput({ arguments: toolArgs });
};
McpUiInitializedNotification for the notification typesendToolInput for sending tool arguments to the ViewRegister a handler for list prompts requests from the view.
The view sends prompts/list requests to enumerate available MCP
prompts. This handler allows the host to intercept and process these
requests, typically by forwarding them to the MCP server.
Handler that receives list params and returns a
ListPromptsResult
params - Request params (may include cursor for pagination)extra - Request metadata (abort signal, session info)Register a handler for list resources requests from the view.
The view sends resources/list requests to enumerate available MCP
resources. This handler allows the host to intercept and process these
requests, typically by forwarding them to the MCP server.
Handler that receives list params and returns a
ListResourcesResult
params - Request params (may include cursor for pagination)extra - Request metadata (abort signal, session info)Register a handler for list resource templates requests from the view.
The view sends resources/templates/list requests to enumerate available
MCP resource templates. This handler allows the host to intercept and process
these requests, typically by forwarding them to the MCP server.
Handler that receives list params and returns a
ListResourceTemplatesResult
params - Request params (may include cursor for pagination)extra - Request metadata (abort signal, session info)Register a handler for logging messages from the view.
The view sends standard MCP notifications/message (logging) notifications
to report debugging information, errors, warnings, and other telemetry to the
host. The host can display these in a console, log them to a file, or send
them to a monitoring service.
This uses the standard MCP logging notification format, not a UI-specific message type.
Handler that receives logging params
params.level - Log level: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency"params.logger - Optional logger name/identifierparams.data - Log message and optional structured dataRegister a handler for message requests from the view.
The view sends ui/message requests when it wants to add a message to
the host's chat interface. This enables interactive apps to communicate with
the user through the conversation thread.
The handler should process the message (add it to the chat) and return a result indicating success or failure. For security, the host should NOT return conversation content or follow-up results to prevent information leakage.
Handler that receives message params and returns a result
params.role - Message role (currently only "user" is supported)params.content - Message content blocks (text, image, etc.)extra - Request metadata (abort signal, session info)Promise<McpUiMessageResult> with optional isError flagbridge.onmessage = async ({ role, content }, extra) => {
try {
await chatManager.addMessage({ role, content, source: "app" });
return {}; // Success
} catch (error) {
console.error("Failed to add message:", error);
return { isError: true };
}
};
McpUiMessageRequest for the request typeMcpUiMessageResult for the result typeRegister a handler for external link requests from the view.
The view sends ui/open-link requests when it wants to open an external
URL in the host's default browser. The handler should validate the URL and
open it according to the host's security policy and user preferences.
The host MAY:
Handler that receives URL params and returns a result
params.url - URL to open in the host's browserextra - Request metadata (abort signal, session info)Promise<McpUiOpenLinkResult> with optional isError flagbridge.onopenlink = async ({ url }, extra) => {
if (!isAllowedDomain(url)) {
console.warn("Blocked external link:", url);
return { isError: true };
}
const confirmed = await showDialog({
message: `Open external link?\n${url}`,
buttons: ["Open", "Cancel"],
});
if (confirmed) {
window.open(url, "_blank", "noopener,noreferrer");
return {};
}
return { isError: true };
};
McpUiOpenLinkRequest for the request typeMcpUiOpenLinkResult for the result typeRegister a handler for read resource requests from the view.
The view sends resources/read requests to retrieve the contents of an
MCP resource. This handler allows the host to intercept and process these
requests, typically by forwarding them to the MCP server.
Handler that receives read params and returns a
ReadResourceResult
params - Read parameters including the resource URIextra - Request metadata (abort signal, session info)Register a handler for display mode change requests from the view.
The view sends ui/request-display-mode requests when it wants to change
its display mode (e.g., from "inline" to "fullscreen"). The handler should
check if the requested mode is in availableDisplayModes from the host context,
update the display mode if supported, and return the actual mode that was set.
If the requested mode is not available, the handler should return the current display mode instead.
By default, AppBridge returns the current displayMode from host context (or "inline").
Setting this property replaces that default behavior.
Handler that receives the requested mode and returns the actual mode set
params.mode - The display mode being requested ("inline" | "fullscreen" | "pip")extra - Request metadata (abort signal, session info)Promise<McpUiRequestDisplayModeResult> with the actual mode setbridge.onrequestdisplaymode = async ({ mode }, extra) => {
if (availableDisplayModes.includes(mode)) {
currentDisplayMode = mode;
}
return { mode: currentDisplayMode };
};
McpUiRequestDisplayModeRequest for the request typeMcpUiRequestDisplayModeResult for the result typeInternalRegister a handler for sandbox proxy ready notifications.
This is an internal callback used by web-based hosts implementing the
double-iframe sandbox architecture. The sandbox proxy sends
ui/notifications/sandbox-proxy-ready after it loads and is ready to receive
HTML content.
When this fires, the host should call sendSandboxResourceReady with
the HTML content to load into the inner sandboxed iframe.
bridge.onsandboxready = async () => {
const resource = await mcpClient.request(
{ method: "resources/read", params: { uri: "ui://my-app" } },
ReadResourceResultSchema
);
bridge.sendSandboxResourceReady({
html: resource.contents[0].text,
sandbox: "allow-scripts"
});
};
McpUiSandboxProxyReadyNotification for the notification typesendSandboxResourceReady for sending content to the sandboxRegister a handler for size change notifications from the view.
The view sends ui/notifications/size-changed when its rendered content
size changes, typically via ResizeObserver. Set this callback to dynamically
adjust the iframe container dimensions based on the view's content.
Note: This is for View → Host communication. To notify the View of
host container dimension changes, use setHostContext.
bridge.onsizechange = ({ width, height }) => {
if (width != null) {
iframe.style.width = `${width}px`;
}
if (height != null) {
iframe.style.height = `${height}px`;
}
};
McpUiSizeChangedNotification for the notification typeApp.sendSizeChanged - the View method that sends these notificationsRegister a handler for model context updates from the view.
The view sends ui/update-model-context requests to update the Host's
model context. Each request overwrites the previous context stored by the view.
Unlike logging messages, context updates are intended to be available to
the model in future turns. Unlike messages, context updates do not trigger follow-ups.
The host will typically defer sending the context to the model until the
next user message (including ui/message), and will only send the last
update received.
bridge.onupdatemodelcontext = async (
{ content, structuredContent },
extra,
) => {
// Store the context snapshot for inclusion in the next model request
modelContextManager.update({ content, structuredContent });
return {};
};
McpUiUpdateModelContextRequest for the request type
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 guest supports the capability required for the given request method.
InternalVerify that the host supports the capability required for the given notification method.
InternalVerify that a request handler is registered and supported for the given method.
ProtectedassertInternalVerify that task creation is supported for the given request method.
ProtectedassertInternalVerify that task handler is supported for the given method.
ProtectedcancelExperimentalCancels a specific task.
Use client.experimental.tasks.cancelTask() to access this method.
Optionaloptions: RequestOptionsCloses the connection.
Connect to the view via transport and optionally set up message forwarding.
This method establishes the transport connection. If an MCP client was passed to the constructor, it also automatically sets up request/notification forwarding based on the MCP server's capabilities, proxying the following to the view:
If no client was passed to the constructor, no automatic forwarding is set up
and you must register handlers manually using the oncalltool, onlistresources,
etc. setters.
After calling connect, wait for the oninitialized callback before sending
tool input and other data to the View.
Transport layer (typically PostMessageTransport)
Promise resolving when connection is established
If a client was passed but server capabilities are not available.
This occurs when connect() is called before the MCP client has completed its
initialization with the server. Ensure await client.connect() completes
before calling bridge.connect().
const bridge = new AppBridge(mcpClient, hostInfo, capabilities);
const transport = new PostMessageTransport(
iframe.contentWindow!,
iframe.contentWindow!,
);
bridge.oninitialized = () => {
console.log("View ready");
bridge.sendToolInput({ arguments: toolArgs });
};
await bridge.connect(transport);
Get the view's capabilities discovered during initialization.
Returns the capabilities that the view advertised during its
initialization request. Returns undefined if called before
initialization completes.
view capabilities, or undefined if not yet initialized
bridge.oninitialized = () => {
const caps = bridge.getAppCapabilities();
if (caps?.tools) {
console.log("View provides tools");
}
};
McpUiAppCapabilities for the capabilities structure
Get the view's implementation info discovered during initialization.
Returns the view's name and version as provided in its initialization
request. Returns undefined if called before initialization completes.
view implementation info, or undefined if not yet initialized
Get the host capabilities passed to the constructor.
Host capabilities object
McpUiHostCapabilities for the capabilities structure
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: RequestOptionsProtectedlistExperimentalLists 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: NotificationOptionsRemoves 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: RequestOptionsProtectedrequestExperimentalSends 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.
Low-level method to notify the view of host context changes.
Most hosts should use setHostContext instead, which automatically
detects changes and calls this method with only the modified fields.
Use this directly only when you need fine-grained control over change detection.
The context fields that have changed (partial update)
Notify the view that the MCP server's prompt list has changed.
The host sends notifications/prompts/list_changed to the view when it
receives this notification from the MCP server. This allows the view
to refresh its prompt cache or UI accordingly.
Optional notification params (typically empty)
Notify the view that the MCP server's resource list has changed.
The host sends notifications/resources/list_changed to the view when it
receives this notification from the MCP server. This allows the view
to refresh its resource cache or UI accordingly.
Optional notification params (typically empty)
InternalSend HTML resource to the sandbox proxy for secure loading.
This is an internal method used by web-based hosts implementing the
double-iframe sandbox architecture. After the sandbox proxy signals readiness
via ui/notifications/sandbox-proxy-ready, the host sends this notification
with the HTML content to load.
HTML content and sandbox configuration:
html: The HTML content to load into the sandboxed iframesandbox: Optional sandbox attribute value (e.g., "allow-scripts")Optionalcsp?: McpUiResourceCspOptionalpermissions?: McpUiResourcePermissionsOptionalsandbox?: stringonsandboxready for handling the sandbox proxy ready notification
Notify the view that tool execution was cancelled.
The host MUST send this notification if tool execution was cancelled for any reason, including user action, sampling error, classifier intervention, or any other interruption. This allows the view to update its state and display appropriate feedback to the user.
Cancellation details object
reason: Human-readable explanation for why the tool was cancelledOptionalreason?: string// User clicked "Cancel" button
bridge.sendToolCancelled({ reason: "User cancelled the operation" });
// Sampling error or timeout
bridge.sendToolCancelled({ reason: "Request timeout after 30 seconds" });
// Classifier intervention
bridge.sendToolCancelled({ reason: "Content policy violation detected" });
McpUiToolCancelledNotification for the notification typesendToolResult for sending successful resultssendToolInput for sending tool argumentsSend complete tool arguments to the view.
The host MUST send this notification after the View completes initialization
(after oninitialized callback fires) and complete tool arguments become available.
This notification is sent exactly once and is required before sendToolResult.
Complete tool call arguments
Optionalarguments?: Record<string, unknown>bridge.oninitialized = () => {
bridge.sendToolInput({
arguments: { location: "New York", units: "metric" },
});
};
McpUiToolInputNotification for the notification typeoninitialized for the initialization callbacksendToolResult for sending results after executionSend streaming partial tool arguments to the view.
The host MAY send this notification zero or more times while tool arguments
are being streamed, before sendToolInput is called with complete
arguments. This enables progressive rendering of tool arguments in the
view.
The arguments represent best-effort recovery of incomplete JSON. views SHOULD handle missing or changing fields gracefully between notifications.
Partial tool call arguments (may be incomplete)
Optionalarguments?: Record<string, unknown>// As streaming progresses...
bridge.sendToolInputPartial({ arguments: { loc: "N" } });
bridge.sendToolInputPartial({ arguments: { location: "New" } });
bridge.sendToolInputPartial({ arguments: { location: "New York" } });
// When complete, send final input
bridge.sendToolInput({
arguments: { location: "New York", units: "metric" },
});
McpUiToolInputPartialNotification for the notification typesendToolInput for sending complete argumentsNotify the view that the MCP server's tool list has changed.
The host sends notifications/tools/list_changed to the view when it
receives this notification from the MCP server. This allows the view
to refresh its tool cache or UI accordingly.
Optional notification params (typically empty)
Send tool execution result to the view.
The host MUST send this notification when tool execution completes successfully,
provided the view is still displayed. If the view was closed before execution
completes, the host MAY skip this notification. This must be sent after
sendToolInput.
Standard MCP tool execution result
const result = await mcpClient.request(
{ method: "tools/call", params: { name: "get_weather", arguments: args } },
CallToolResultSchema,
);
bridge.sendToolResult(result);
McpUiToolResultNotification for the notification typesendToolInput for sending tool arguments before resultsUpdate the host context and notify the view of changes.
Compares fields present in the new context with the current context and sends a
ui/notifications/host-context-changed notification containing only fields
that have been added or modified. If no fields have changed, no notification is sent.
The new context fully replaces the internal state.
Common use cases include notifying the view when:
The complete new host context state
bridge.setHostContext({
theme: "dark",
containerDimensions: { maxHeight: 600, width: 800 },
});
McpUiHostContext for the context structureMcpUiHostContextChangedNotification for the notification typeRegisters 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 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 graceful shutdown of the view.
The host MUST send this request before tearing down the UI resource (before unmounting the iframe). This gives the view an opportunity to save state, cancel pending operations, or show confirmation dialogs.
The host SHOULD wait for the response before unmounting to prevent data loss.
Empty params object
Optionaloptions: RequestOptionsRequest options (timeout, etc.)
Promise resolving when view confirms readiness for teardown
Host-side bridge for communicating with a single View (
App).AppBridgeextends the MCP SDK'sProtocolclass and acts as a proxy between the host application and a view running in an iframe. When an MCP client is provided to the constructor, it automatically forwards MCP server capabilities (tools, resources, prompts) to the view. It also handles the initialization handshake.Architecture
View ↔ AppBridge ↔ Host ↔ MCP Server
The bridge proxies requests from the view to the MCP server and forwards responses back. It also sends host-initiated notifications like tool input and results to the view.
Lifecycle
AppBridgewith MCP client and capabilitiesconnect()with transport to establish communicationsendToolInput,sendToolResult, etc.teardownResourcebefore unmounting iframeExample: Basic usage