@mcp-web/app

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. A Vite plugin handles bundling each app into a self-contained HTML file.

Quick Start

Installation

npm install @mcp-web/app

1. Define an App

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

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):

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

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

Build with:

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:

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

mcp.addApp(statsApp);

Input Schemas

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

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:

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:

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

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.