MCP Apps

Build a React widget, bundle it as HTML, and return it with a Toolgrain tool.

An MCP App is an HTML widget that a compatible MCP host displays when it calls your tool. Your server still returns useful data for the assistant; the widget adds a React interface beside it.

Start with Build your first widget. It begins with the Vite CLI and shows every file you need to edit.

​

The three pieces

Piece	What you write
Tool	A normal Toolgrain tool() that returns data and points to a widget URI
Widget	React components using AppProvider and useToolResult()
Resource	A resource() that returns the widget’s built HTML

Vite turns weather.html into dist/widgets/weather.html. The resource serves that file under a URI such as ui://weather/widget.html. The host loads the HTML and delivers the tool result to React.

Toolgrain handles the native Apps connection, result delivery, host styling, and widget sizing. Your application owns its UI and build. The host owns iframe creation, sandboxing, CSP enforcement, and permission grants.

​

Follow the guides in order

1. Build your first widget: scaffold a React app, add the tool and resource, and connect a host.
2. Use React hooks: add refresh calls, loading/error states, and optional host context.
3. Add more widgets: build a separate HTML file for each resource.
4. Permissions and metadata: edit one configuration object for the widget’s needs.

For existing servers, use Link tools and widgets. Shared entries and host actions are optional follow-ups.

Apps and React are available in Toolgrain 0.3.0 or later. Install matching versions across Toolgrain packages. Compatibility and acceptance records exact tested builds and live-host coverage.

Toolgrain implements the Apps protocol natively, without the official MCP or Apps SDKs. The iframe uses Apps revision 2026-01-26, independently of the outer MCP connection. See the protocol support table for the implemented messages.