Called 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 ViewUse addEventListener("initialized", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
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.
The handler receives LoggingMessageNotification["params"]:
level — "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency"logger — optional logger name/identifierdata — log message and optional structured databridge.onloggingmessage = ({ level, logger, data }) => {
console[level === "error" ? "error" : "log"](
`[${logger ?? "View"}] ${level.toUpperCase()}:`,
data,
);
};
Use addEventListener("loggingmessage", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
Register a handler for app-initiated teardown request notifications from the view.
The view sends ui/notifications/request-teardown when it wants the host to tear it down.
If the host decides to proceed, it should send
ui/resource-teardown (via teardownResource) to allow
the view to perform gracefull termination, then unmount the iframe after the view responds.
bridge.onrequestteardown = async (params) => {
console.log("App requested teardown");
// Initiate teardown to allow the app to persist unsaved state
// Alternatively, the callback can early return to prevent teardown
await bridge.teardownResource({});
// Now safe to unmount the iframe
iframe.remove();
};
McpUiRequestTeardownNotification for the notification typeteardownResource for initiating teardownUse addEventListener("requestteardown", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
InternalRegister 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" } }
);
bridge.sendSandboxResourceReady({
html: resource.contents[0].text,
sandbox: "allow-scripts"
});
};
McpUiSandboxProxyReadyNotification for the notification typesendSandboxResourceReady for sending content to the sandboxUse addEventListener("sandboxready", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
Register 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 notificationsUse addEventListener("sizechange", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
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 (ProtocolOptions from the base MCP SDK plus hostContext)
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_The base MCP SDK calls this hook for every standard and custom request
handler registration. AppBridge uses it to preserve the existing warning
when a View calls host methods before ui/notifications/initialized,
without adding overload-forwarding adapters around setRequestHandler.
ui/initialize and ping are exempt because they are valid before the
Apps-ready gate. This wraps registered callbacks, not JSON-RPC dispatch.
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 view supports the capability required for the given request method.
ProtectedassertInternalVerify that the host supports the capability required for the given notification method.
ProtectedassertInternalVerify that a request handler is registered and supported for the given method.
ProtectedbuildInternalCall a tool on the view.
Sends a tools/call request to the view and returns the result.
Tool call parameters (name and arguments)
Optionaloptions: RequestOptionsRequest options (timeout, abort signal, etc.)
Promise resolving to the tool call result
Closes 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
ProtectedgetList tools available on the view.
Sends a tools/list request to the view and returns the result.
List tools parameters (may include cursor for pagination)
Optionaloptions: RequestOptionsRequest options (timeout, abort signal, etc.)
Promise resolving to the list of tools
Emits a notification, which is a one-way message that does not expect a response.
Optionaloptions: NotificationOptionsSends 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: RequestOptionsLow-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 },
});
bridge.sendToolResult(result);
McpUiToolResultNotification for the notification typesendToolInput for sending tool arguments before resultsProtectedsetUpdate 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 typeRequest 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
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.
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)
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 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
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.
Host-side bridge for communicating with a single View (
App).AppBridgeextends the base MCP SDK's publicProtocolclass and acts as a proxy between the host application and a view running in an iframe. When a separate MCP client is provided to the constructor, it automatically forwards MCP server capabilities (tools, resources, prompts) to the view. It also handles the Apps 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