> ## Documentation Index
> Fetch the complete documentation index at: https://toolgrain.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://toolgrain.mintlify.site/mcp-apps/quickstart.md). 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](https://toolgrain.mintlify.site/mcp-apps/quickstart.md): scaffold a React app, add the tool and resource, and connect a host.
2. [Use React hooks](https://toolgrain.mintlify.site/mcp-apps/react.md): add refresh calls, loading/error states, and optional host context.
3. [Add more widgets](https://toolgrain.mintlify.site/mcp-apps/build.md): build a separate HTML file for each resource.
4. [Permissions and metadata](https://toolgrain.mintlify.site/mcp-apps/security.md): edit one configuration object for the widget's needs.

For existing servers, use [Link tools and widgets](https://toolgrain.mintlify.site/mcp-apps/server.md). [Shared entries](https://toolgrain.mintlify.site/mcp-apps/shared-entries.md) and [host actions](https://toolgrain.mintlify.site/mcp-apps/host-actions.md) are optional follow-ups.

> [!NOTE]
>
> Apps and React are available in Toolgrain 0.3.0 or later. Install matching versions across Toolgrain packages. [Compatibility and acceptance](https://toolgrain.mintlify.site/mcp-apps/compatibility.md) 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](https://toolgrain.mintlify.site/mcp-apps/capabilities.md#react-protocol-support) for the implemented messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.