Sales Explorer — a minimal MCP App

A tiny, dependency-light demo of an MCP App: an interactive UI that an MCP server ships into an AI host (Claude, etc.), rendered in a sandboxed iframe right in the conversation.

The whole point is one moment: you click a bar and the chart drills down with no model round-trip — and the assistant still knows what you're looking at.

The three beats this demonstrates

1. UI in the chat, not text. Ask "show me sales by region" → a bar chart renders inline instead of a table of numbers.
2. Bidirectional, model-free interaction. Click a region → the iframe calls the get_sales tool itself and re-renders. No new prompt, no model turn.
3. The model stays in the loop. After drilling in, the app tells the host what you're viewing, so you can then say "email this to my team" and it knows what "this" is.

How it works (the two files that matter)

• server.ts — registers a tool (get_sales) whose _meta.ui.resourceUri points at a UI resource (ui://sales-explorer/mcp-app.html). That one line of metadata is what turns a normal tool into an MCP App.
• src/mcp-app.ts — the iframe app. It renders the chart from the result the host pushes in (app.ontoolresult), and on a bar click calls app.callServerTool({ name: "get_sales", arguments: { region } }).

The UI is bundled by Vite into a single self-contained HTML file (dist/mcp-app.html) so the server can return it as one resource with no external asset requests.

Run it

Requires Node ≥ 22.18 (run TypeScript directly — no tsx/ts-node).

npm install
npm run dev        # builds the UI on change + serves MCP over HTTP on :3001

• HTTP endpoint: http://localhost:3001/mcp (Streamable HTTP, stateless)
• stdio: npm run start:stdio

Then point an MCP-Apps-capable host at it (Claude Desktop, MCPJam, VS Code Copilot, …) and ask: "show me sales by region."

Verify without a host (curl)

npm start &   # build UI + serve

# list tools — note the _meta.ui.resourceUri on get_sales
curl -s -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -X POST http://localhost:3001/mcp \
     --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# the drill-down the iframe performs on a click
curl -s -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -X POST http://localhost:3001/mcp \
     --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_sales","arguments":{"region":"EMEA"}}}'

Project layout

server.ts          # MCP server: get_sales tool + ui:// resource
main.ts            # transport (Streamable HTTP / stdio)
mcp-app.html       # UI shell (bundled into dist/mcp-app.html)
src/mcp-app.ts     # the iframe app: render chart, click -> callServerTool
src/styles.css     # chart styling (uses host theme variables when provided)
vite.config.ts     # single-file bundle config

Built on @modelcontextprotocol/ext-apps + @modelcontextprotocol/sdk.