Key Concepts

This guide will introduce you to everything you need to know to understand the fractal ecosystem, but assumes basic knowledge of AI agents and MCP.

High level overview

The goal of Fractal is to enable chats to have nice UI components embedded directly within.

The basic flow of data looks something like this:

A user prompts an agent to help with a task
The agent decides to call a tool
The tool returns a UI component to the agent
The agent forwards the UI component to the chat UI.
The chat UI displays the component for the user.

A couple things must happen to make this possible:

Standardized `UIResource` Interface

MCP clients and servers must agree on a standardized format for representing UI components in a tool response. The UIResource introduced by MCP UI is a solid candidate for standardization.

Iframes for secure rendering

Chat applications need an isolated environment for securely rendering UIResources from untrusted sources. Iframes do the trick here. With an iframe you can render raw HTML (which are often faster and permits more ergonomic dev tooling) or you can render external URLs (which are more secure and simple to reason about as standalone apps).

Fractal `UIMessenger` Protocol

The isolation that iframes give is a double edged sword - we achieve some level of security but it costs us responsiveness in the UI. Without some aditional wiring, components running within the iframe won’t be able to receive data to from outside the iframe, the parent won’t know what size to assign the iframe component, and key events such as link clicks wont open new tabs.

We address this with a messaging protocol between the iframe and its parent. This messaging protocol allows the embedded component to receive render data from the parent, and notify it of key events, such as links being clicked, the component resizing, the user presses a button, etc. Some of these notifications happen automatically, such as data passing and component resizing. Other operations are at the discretion of the developer. For example, to allow a user to open a link from an embedded component, the MCP dev must define something like this:


const {link} = useUIMessenger()
// ...
onClick={() => link("https://example.com")}

The useUIMessenger hook can be imported from @fractal-mcp/server-ui-react, and handles the embedded side of the UIMessenger protocol.

and the chat agent dev must properly handle these events.

Check out this guide for more information on bundling.

A Beefed Up Iframe Component

Fractal’s @fractal-mcp/client-ui-react library exports a FractalUIResourceRenderer component which renders a UIResource in an iframe and handles setting up the client side of the UIMessenger protocol.

Component Bundling

FractalUIResourceRenderer can handle both external URLs and raw HTML.

For developers who have an existing application which they would like to repurpose, the quickest path is to point UIResources towards the URL of the existing hosted application.

But if you don’t have an existing application or if you need optimized performance, you can try bundling your component into a single HTML file and passing it as raw HTML in your UIResource.

You can use the npx @fractal-mcp/cli bundle command.