React renderer for MCP Apps

[ochafik]

AppRenderer is a renderer for tool calls that return MCP Apps, adapted from this example to accept an optional MCP-UI onUIAction callback.

Apps can be created with the SDK at https://github.com/modelcontextprotocol/ext-apps

More details on SEP-1865

Requires updating MCP TS SDK from 1.11 to 1.22: sent separately as #148, merged here

cc/ @idosal @liady @antonpk1

[infoxicator]

Suggested change

	export { UITemplatedToolCallRenderer, type UITemplatedToolCallRendererProps } from './components/UITemplatedToolCallRenderer';
	export { AppRenderer, type AppRendererProps } from './components/AppRenderer';';

[ochafik]

✅ Fixed in e0c4421 — replaced the broken UITemplatedToolCallRenderer with AppRenderer export.

[infoxicator]

@ochafik this is convenient so we get the resource automatically and all the logic is encapsulated in the renderer, but in my case passing the entire client instance is tricky. What you think about having an additional mode where the resource (or its html) can be passed to the renderer directly and it is up to the client how to get that?

[idosal]

@infoxicator @ochafik Can we extract this component from AppRenderer so we'll export both the bare-bones component and the higher-level renderer on top of it?
I can take a stab at it later.

[chelojimenez]

hi @ochafik, we built our own renderer in MCPJam to provide initial support of MCP Apps, this renderer like @infoxicator points out, we pass HTML directly rather than requiring an MCP client instance (This pattern works well when the MCP client lives in a different context and ours lives in the server). Happy to discuss any of these if useful!

[liady]

@chelojimenez yeah, it's much simpler if the host can extract the HTML itself and pass it, and I agree that in your case it's even the only way (since the rendering context doesn't have an access to the client instance).
Note that @ochafik 's usage here is much wider - since this implementation relies on the AppBridge (from the ext-apps repo) - which needs the client in order to proxy MCP requests.
In the MCPJam implementation this is not needed - mcp-apps-renderer actually doesn't rely on MCP at all - and simply parses messages according to the schema. (It's a good renderer btw, even if it's not "generic" in that sense).

It's a good question regarding how we want to build the generic client side renderer here. @ochafik 's implementation encapsulates a lot of the functionality (including HTML resource mathcing) - but requires the client instance. On the other hand a more "low-level" renderer would leave more heavy-lifting to the host, and if we skip using AppBridge we might be missing the MCP re-use.

As @idosal is also working on the client side SDK, we'll probably need to align on the best abstraction here. I think that allowing (optionally) to pass the raw resource HTML instead of the entire client is a good, but we still need to solve for the usage of AppBridge that does require the client instance.

[infoxicator]

I am experimenting using a facade / relay pattern to proxy the mcp events without having to pass the entire client. its working on postman but I will need some time to figure out how to make it fully reusable and also provide it as an alternative to passing the client

[ochafik]

(sorry for the noise, toying w/ updates to AppBridge to not require a Client / give users more flexibility)

[ochafik]

Making Client optional here: modelcontextprotocol/ext-apps#146

[idosal]

Perhaps we should change it to a sandbox prop with an internal object for url. I imagine sandbox will have additional properties in the future (such as permissions). WDYT?

[ochafik]

Addressed in d12ddcc:

1. sandbox prop with object structure:

// Before
sandboxProxyUrl={new URL('...')}

// After
sandbox={{ url: new URL('...'), permissions?: string, csp?: McpUiResourceCsp }}

sandboxProxyUrl still works with a deprecation warning.

2. Extracted bare-bones component:

• AppFrame — low-level, takes html directly + optional appBridge
• AppRenderer — high-level, fetches resources, creates bridge internally

Both are exported from @mcp-ui/client.

[guru3s]

this should be .values[0]

[ochafik]

✅ Fixed in e0c4421 — good catch on the Zod v4 API change!

[ochafik]

(sorry for the delay, back on this!)

[aharvard]

This is great! Looking forward to using it in Goose when ready.

[ochafik]

@guru3s ✅ Fixed in e0c4421 — good catch on the Zod v4 API change!

[ochafik]

Update: Setter-based MCP forwarding in AppBridge

Merged latest main and updated @modelcontextprotocol/ext-apps to use a new branch with a cleaner API design.

Changes in ext-apps (ochafik/app-bridge-setters)

Made Client optional in AppBridge constructor - hosts can now pass null and register handlers manually:

// Option 1: With client (automatic forwarding - existing behavior)
const bridge = new AppBridge(mcpClient, hostInfo, capabilities);

// Option 2: Without client (manual handlers)
const bridge = new AppBridge(null, hostInfo, capabilities);
bridge.oncalltool = async (params, extra) => { /* custom handling */ };
bridge.onlistresources = async (params, extra) => { /* custom handling */ };

New setter-based handlers for Guest UI → Host requests:

• oncalltool - handle tools/call requests
• onlistresources - handle resources/list requests
• onlistresourcetemplates - handle resources/templates/list requests
• onreadresource - handle resources/read requests
• onlistprompts - handle prompts/list requests

New send methods for Host → Guest notifications:

• sendToolListChanged()
• sendResourceListChanged()
• sendPromptListChanged()

Why this matters

The previous design required a full MCP Client and automatically wired up all forwarding. The new design enables:

• Static HTML UIs with no MCP calls
• Custom/filtered MCP proxying (e.g., caching, authorization, logging)
• Multi-server aggregation
• Testing without a real MCP client

Build/test status

• ✅ All 120 client tests pass
• ✅ Build succeeds

[infoxicator]

@ochafik I am considering using the onReadResource prop here instead of requiring the entire client.

Passing the HTML directly works but it would be nice if this component contains the logic for getting the getToolUiResourceUri and readToolUiResourceHtml as well without the need for the client

[ochafik]

Done in fece80e! The component now supports fetching HTML without a Client by providing toolResourceUri + onReadResource:

<AppRenderer
  toolName="my-tool"
  toolResourceUri="ui://my-server/my-tool"
  onReadResource={async ({ uri }) => myProxy.readResource({ uri })}
  onCallTool={async (params) => myProxy.callTool(params)}
/>

This enables decoupled architectures where the MCP client lives in a different context.

[infoxicator]

Working great so far @ochafik

One comment to make the decoupling of client complete and then we are mostly there 🙌

[aharvard]

@ochafik, I was testing AppRenderer in Goose and found this tiny nit modelcontextprotocol/ext-apps#156

[infoxicator]

@ochafik small nit. We can mark the Client as optional? and check for undefined instead of having to pass null?

[ochafik]

Done in fece80e! Changed from client: Client | null to client?: Client

[Copilot]

Pull request overview

This PR introduces React renderer components for MCP Apps, enabling hosts to render tool UIs in sandboxed iframes with bidirectional MCP communication. The implementation is adapted from the modelcontextprotocol/ext-apps example and adds support for the MCP Apps SEP-1865 protocol, including updating the MCP TypeScript SDK from 1.11 to 1.23.

Key changes:

• Adds AppRenderer component for high-level tool UI rendering with automatic resource fetching and AppBridge management
• Adds AppFrame component for low-level sandbox iframe rendering with pre-configured AppBridge
• Adds utility functions for sandbox setup and resource reading (app-host-utils.ts)

Reviewed changes

Copilot reviewed 15 out of 19 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
sdks/typescript/client/src/components/AppRenderer.tsx	New component providing high-level interface for rendering MCP tool UIs with automatic AppBridge setup, resource fetching, and MCP request handling
sdks/typescript/client/src/components/AppFrame.tsx	New low-level component for rendering pre-fetched HTML in sandboxed iframe with AppBridge communication
sdks/typescript/client/src/utils/app-host-utils.ts	New utilities for sandbox iframe setup, tool resource URI resolution, and HTML reading
sdks/typescript/client/src/components/__tests__/AppRenderer.test.tsx	Comprehensive test suite for AppRenderer covering rendering, props, callbacks, and ref methods
sdks/typescript/client/src/components/__tests__/AppFrame.test.tsx	Comprehensive test suite for AppFrame covering sandbox setup, bridge connection, and message handling
sdks/typescript/client/src/index.ts	Exports new AppRenderer, AppFrame components and re-exports AppBridge types for public API
sdks/typescript/client/package.json	Updates MCP SDK to 1.23.0, adds ext-apps dependency, and adds zod dependency
examples/mcp-apps-demo/package.json	Updates ext-apps dependency to use GitHub main branch reference
eslint.config.mjs	New ESLint flat config with TypeScript and React support, replaces legacy configuration
sdks/typescript/client/src/utils/processResource.ts	Whitespace formatting fix (trailing whitespace removed)
sdks/typescript/client/src/remote-dom/iframe-bundle.ts	Updates bundled remote-dom and quilted/threads libraries to newer versions
Various test files	Formatting improvements (consistent indentation, whitespace cleanup)
Various component files	Formatting improvements (trailing whitespace removal, consistent indentation)

[Copilot]

The sandbox attribute is hardcoded to allow-scripts allow-same-origin allow-forms. While these permissions are necessary for the sandbox to function, the allow-same-origin permission combined with allow-scripts effectively removes the security sandbox. This is a known security concern. Consider documenting why this is necessary and if there are alternative approaches. Also, the sandbox configuration should ideally be configurable via the SandboxConfig interface to allow hosts to enforce stricter policies if needed.

[Copilot]

The _reject parameter in the Promise constructor is unused and should be prefixed with an underscore or removed if truly unused. Currently, the promise never rejects, which means the caller cannot handle setup failures. Consider adding error handling and rejection logic, or document why rejection is not needed.

Suggested change

	const onReady = new Promise<void>((resolve, _reject) => {
	const initialListener = async (event: MessageEvent) => {
	if (event.source === iframe.contentWindow) {
	if (
	event.data &&
	event.data.method === McpUiSandboxProxyReadyNotificationSchema.shape.method._def.values[0]
	) {
	window.removeEventListener('message', initialListener);
	resolve();
	}
	}
	};
	window.addEventListener('message', initialListener);
	const onReady = new Promise<void>((resolve, reject) => {
	let settled = false;
	const timeoutMs = 10000; // 10 seconds
	const timeoutId = setTimeout(() => {
	if (!settled) {
	settled = true;
	window.removeEventListener('message', initialListener);
	iframe.removeEventListener('error', errorListener);
	reject(new Error('Timed out waiting for sandbox proxy iframe to be ready'));
	}
	}, timeoutMs);
	const initialListener = async (event: MessageEvent) => {
	if (event.source === iframe.contentWindow) {
	if (
	event.data &&
	event.data.method === McpUiSandboxProxyReadyNotificationSchema.shape.method._def.values[0]
	) {
	if (!settled) {
	settled = true;
	clearTimeout(timeoutId);
	window.removeEventListener('message', initialListener);
	iframe.removeEventListener('error', errorListener);
	resolve();
	}
	}
	}
	};
	const errorListener = () => {
	if (!settled) {
	settled = true;
	clearTimeout(timeoutId);
	window.removeEventListener('message', initialListener);
	iframe.removeEventListener('error', errorListener);
	reject(new Error('Failed to load sandbox proxy iframe'));
	}
	};
	window.addEventListener('message', initialListener);
	iframe.addEventListener('error', errorListener);

[Copilot]

Accessing array element [0] using bracket notation on a Zod schema definition is fragile. This assumes the schema structure and internal Zod implementation details. If the Zod schema shape changes in future versions, this code will break. Consider using a more robust approach, such as defining the expected message type as a constant or using Zod's type extraction methods.

Suggested change

	const onReady = new Promise<void>((resolve, _reject) => {
	const initialListener = async (event: MessageEvent) => {
	if (event.source === iframe.contentWindow) {
	if (
	event.data &&
	event.data.method === McpUiSandboxProxyReadyNotificationSchema.shape.method._def.values[0]
	// Define the expected method string for the ready notification.
	// This should match the value used in the schema definition.
	const MCP_UI_SANDBOX_PROXY_READY_METHOD = 'mcp.ui.sandboxProxy.ready';
	const onReady = new Promise<void>((resolve, _reject) => {
	const initialListener = async (event: MessageEvent) => {
	if (event.source === iframe.contentWindow) {
	if (
	event.data &&
	event.data.method === MCP_UI_SANDBOX_PROXY_READY_METHOD

[Copilot]

The new AppRenderer and AppFrame components are exported but lack documentation. These are significant new public APIs that should be documented similarly to the existing UIResourceRenderer component. Consider adding documentation pages explaining their purpose, usage examples, API reference, and how they relate to the MCP Apps ecosystem. The existing documentation structure in docs/src/guide/client/ would be a good place for these.

[Copilot]

The dependency @modelcontextprotocol/ext-apps is specified using a GitHub URL reference (github:modelcontextprotocol/ext-apps#main). This is not a stable versioning strategy and can lead to unpredictable behavior as the main branch changes. Consider using a specific commit hash, tag, or published npm version for reproducible builds.

Suggested change

	"@modelcontextprotocol/ext-apps": "github:modelcontextprotocol/ext-apps#main",
	"@modelcontextprotocol/ext-apps": "github:modelcontextprotocol/ext-apps#abcdef1234567890abcdef1234567890abcdef12",

[Copilot]

The error handling doesn't provide specific guidance when both client and html are missing but toolResourceUri is provided without onReadResource. The error message should be clearer about the required combinations. Consider mentioning that toolResourceUri requires either a client or an onReadResource callback.

Suggested change

	"Either 'html' prop, 'client', or ('toolResourceUri' + 'onReadResource') must be provided to fetch UI resource",
	),
	"Unable to fetch UI resource: you must provide one of the following combinations:\n" +
	" - 'html' prop (static HTML provided)\n" +
	" - 'client' (to fetch the resource via MCP)\n" +
	" - 'toolResourceUri' AND either 'client' or 'onReadResource' callback (to fetch the resource by URI)\n" +
	"Note: Providing 'toolResourceUri' alone is not sufficient; you must also provide a 'client' or an 'onReadResource' callback to fetch the resource.",

[Copilot]

Console.log statements are left in production code. These should either be removed, converted to a proper logging mechanism (with configurable log levels), or wrapped in a debug flag. Production code shouldn't have verbose console logs that can expose internal implementation details or clutter user consoles.

[Copilot]

Console.log statements are left in production code. These should either be removed, converted to a proper logging mechanism (with configurable log levels), or wrapped in a debug flag. Production code shouldn't have verbose console logs.

Suggested change

console.log(`[AppRenderer] Reading resource HTML from: ${uri}`);

[Copilot]

Console.log statements are left in production code. These should either be removed, converted to a proper logging mechanism (with configurable log levels), or wrapped in a debug flag.

Suggested change

	console.log('[AppFrame] App initialized');
	if (process.env.NODE_ENV !== 'production') {
	console.log('[AppFrame] App initialized');
	}

[Copilot]

Console.log statements are left in production code. These should either be removed, converted to a proper logging mechanism (with configurable log levels), or wrapped in a debug flag.

[ochafik]

Update: ext-apps v0.2.0 upgrade

Upgraded @modelcontextprotocol/ext-apps to ^0.2.0 and @modelcontextprotocol/sdk to ^1.24.0.

Changes in ext-apps v0.2.0

1. Method renaming (with deprecated aliases):

   • sendResourceTeardown() → teardownResource()
   • sendOpenLink() → openLink() (not used in mcp-ui)

2. MCP SDK moved to peer dependency - requires @modelcontextprotocol/sdk@^1.24.0

3. Optional transport in connect() - can now call without parameters (auto-detects platform)

Changes in mcp-ui

• Updated all packages to use ^0.2.0 instead of github:...#main
• Renamed AppRendererHandle.sendResourceTeardown → teardownResource to align with upstream
• Updated MCP SDK to ^1.24.0 across all packages

Additional fixes

• Added documentation for AppRenderer and AppFrame components in mcp-apps.md
• Fixed promise rejection handling in setupSandboxProxyIframe (timeout + error listener)

All tests pass ✅

[infoxicator]

@ochafik was this change needed? it is causing a resolution issue when trying to install locally ➤ YN0001: │ Error: @mcp-ui/shared@workspace:*: Workspace not found (@mcp-ui/shared@workspace:*) removing this line fixes the error

[infoxicator]

Suggested change

	if (iframeRef.current && containerRef.current?.contains(iframeRef.current)) {
	containerRef.current.removeChild(iframeRef.current);
	}

@ochafik found a lifecycle problem. This code destroys the iframe when the component unmounts. but then the mounting process doesn't happen again (create iframe setHtml). I don't think that's what we want anyway?

The iframe should preserve the state when rerendering instead of destroying and recreating the iframe?

[infoxicator]

nit: There are no clients currently using this so I guess we can omit these deprecated methods?

[idosal]

@ochafik - the eslint update on main caused conflicts with the PR and revealed a few issues. Fixed them all and merged