npm package: @mcp-web/app
Description: Build tooling for MCP Apps - bundle React components into single HTML files for AI UI rendering
Latest version: 0.1.3

# MCP Web App

Tooling for simplify creating MCP Apps from UI components. The packages bundles components into single HTML files that AI agents can render inline in chat interfaces like Claude Desktop.

> [!IMPORTANT]
> We currently only support React. Support for more frameworks will be added in the future.

## Overview

MCP Apps combine a tool (that AI can call) with a visual React component. When the AI calls the tool, the handler returns props which are passed to your component via the [ext-apps protocol](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps). A Vite plugin handles bundling each app into a self-contained HTML file.

## Quick Start

### Installation

```bash
npm install @mcp-web/app
```

### 1. Define an App

Create a file that exports your apps (e.g. `src/mcp-apps.ts`):

```typescript
import { createApp } from '@mcp-web/app';
import { Statistics } from './components/Statistics';

export const statsApp = createApp({
  name: 'show_stats',
  description: 'Display statistics visualization',
  component: Statistics,
  handler: () => ({
    completionRate: 0.75,
    totalTasks: 100,
  }),
});
```

### 2. Add the Vite Build Config

Create a separate Vite config for building apps (e.g. `vite.apps.config.ts`):

```typescript
import react from '@vitejs/plugin-react';
import { defineMCPAppsConfig } from '@mcp-web/app/vite';

export default defineMCPAppsConfig({
  plugins: [react()],
});
```

Build with:

```bash
vite build --config vite.apps.config.ts
```

This auto-discovers apps in `src/mcp-apps.ts` and outputs bundled HTML files to `public/mcp-web-apps/`.

### 3. Register with MCPWeb

In your web app, register the app so the AI agent can call it:

```typescript
import { statsApp } from './mcp-apps';

mcp.addApp(statsApp);
```

## Input Schemas

Apps can accept input from the AI agent using Zod schemas:

```typescript
import { createApp } from '@mcp-web/app';
import { z } from 'zod';
import { Chart } from './components/Chart';

export const chartApp = createApp({
  name: 'show_chart',
  description: 'Display a chart with the given data',
  component: Chart,
  inputSchema: z.object({
    chartType: z.enum(['bar', 'line', 'pie']).describe('Type of chart'),
    title: z.string().describe('Chart title'),
  }),
  handler: ({ chartType, title }) => ({
    chartType,
    title,
    data: getChartData(),
  }),
});
```

## Host Theming

MCP Apps automatically inherit the host's theme. Use these hooks to access it:

```tsx
import { useMCPHostTheme, useMCPHostContext } from '@mcp-web/app';

function MyApp(props: MyProps) {
  const theme = useMCPHostTheme(); // "light" or "dark"
  const hostContext = useMCPHostContext(); // full context (theme, locale, display mode, etc.)

  return <div className={theme === 'dark' ? 'dark' : ''}>{/* ... */}</div>;
}
```

## Receiving Props

Use the `useMCPAppProps` hook to receive props from the tool handler:

```tsx
import { useMCPAppProps } from '@mcp-web/app';

function Statistics() {
  const props = useMCPAppProps<{ completionRate: number; totalTasks: number }>();

  if (!props) return <div>Loading...</div>;

  return (
    <div>
      <p>Completion: {Math.round(props.completionRate * 100)}%</p>
      <p>Total tasks: {props.totalTasks}</p>
    </div>
  );
}
```

## Vite Plugin Options

```typescript
defineMCPAppsConfig(
  { plugins: [react()] },
  {
    appsConfig: 'src/mcp-apps.ts',       // Path to apps config (auto-detected by default)
    outDir: 'public/mcp-web-apps',        // Output directory (default)
    silenceOverrideWarnings: false,        // Suppress build setting override warnings
  }
);
```

## Exports

| Export | Description |
|--------|-------------|
| `createApp` | Define an app with a handler and component |
| `useMCPAppProps` | React hook to receive props from the tool handler |
| `useMCPApp` | Access the ext-apps `App` instance |
| `useMCPHostTheme` | Get the current host theme (`"light"` or `"dark"`) |
| `useMCPHostContext` | Get the full host context |
| `renderMCPApp` | Manually render a component (auto-generated by Vite plugin) |
| `MCPAppProvider` | Context provider (set up automatically by `renderMCPApp`) |
| `defineMCPAppsConfig` | Create a Vite config for building MCP Apps (via `@mcp-web/app/vite`) |

## Learn More

For full documentation, guides, and examples, visit [mcp-web.dev](https://mcp-web.dev).