How to build an MCP App

MCP Apps is an extension to the Model Context Protocol that enables MCP servers to deliver interactive user interfaces to clients.

xmcp supports building MCP apps natively. Get started by running:

npx create-xmcp-app@latest

And select the template:

? Select a template: (Use arrow keys)
 Default 
 GPT App 
❯ MCP App 

This will kickstart your MCP server with the configuration for building an MCP app. You can optionally choose to include Tailwind CSS. By default, widgets are scaffolded using React.

Project Structure

The final project structure will be as follows:

my-mcp-app/
├── src/
│   └── tools/          # Widgets live here
│       └── weather.ts
├── dist/               # Built output (generated)
├── package.json
├── tsconfig.json
└── xmcp.config.ts       # Configuration file for xmcp

All your widgets will be placed in the src/tools directory. You can scaffold new widgets by running:

npx xmcp create widget <widget-name>

Creating a widget

Handler

Compared to the ext-apps approach, xmcp handles resource creation for you. That means you can focus entirely on writing the tool logic that returns a UI to the client, without worrying about any additional setup.

This implies a custom syntax for the tool that will behave as a widget:

import { type ToolMetadata } from "xmcp";
import { useState } from "react";

export const metadata: ToolMetadata = {
  name: "widget-tool",
  description: "Widget Tool",
  _meta: {
    ui: {
      csp: {
        connectDomains: [],
      },
    },
  },
};

export default function widgetHandler() {
  const [state, setState] = useState<string | null>(null);

  return (
    <div>
      <h1>Widget Tool</h1>
      <p>TODO: Implement your widget UI here</p>
    </div>
  );
}

Metadata

There are small differences between usual tools and widgets. You’ll notice the metadata now includes a ui property, which guides xmcp to detect it as an MCP app–compatible component.

export const metadata: ToolMetadata = {
  name: "show-analytics",
  description: "Display analytics dashboard",
  _meta: {
    ui: {
      csp: {
        connectDomains: ["https://api.analytics.com"],
        resourceDomains: ["https://cdn.analytics.com"],
      },
      domain: "https://analytics-widget.example.com",
      prefersBorder: true,
    },
  },
};

Resource-specific properties:

• csp.connectDomains – Origins for fetch/XHR/WebSocket connections
• csp.resourceDomains – Origins for images, scripts, stylesheets, fonts, and media
• domain – Optional dedicated subdomain for the widget's sandbox origin

For more information on widget metadata, see the MCP Apps Widget Metadata documentation.

The handler function is responsible for rendering the widget UI. By default, it uses React, but you can also use template literals to generate HTML markup.

Read more about the different Tool Handlers here.

Next Steps

• Test your MCP app with MCPJam
• Deploy with Vercel