MCP Apps Playground

A demo MCP server showcasing interactive UI capabilities using the MCP Apps Extension (SEP-1865).

Features

• 🔧 MCP Tools - hello_world, list_sort, flame_graph, and feature_flags tools with Zod schema validation
• 📱 Apps Extension - HTML UI via ui:// resources with text/html;profile=mcp-app
• 📦 structuredContent - Data passed to UI via ui/notifications/tool-input
• 💬 Bidirectional - UIs can send messages back to chat via ui/message
• 🚀 Dual Transport - stdio (default) and HTTP/SSE

Tools

list_sort — Interactive List Reordering

Before: Agent receives list data from an MCP tool → proposes a sorted order based on its analysis → user reads text output and requests adjustments → multiple back-and-forth messages to align with actual preferences.

With MCP Apps: Agent displays a drag-and-drop interface alongside its suggested order. User applies domain knowledge to reorder items visually, or clicks "Ask AI to Sort" for the agent's reasoning—true collaboration where both contribute.

🖱️ Drag-and-drop reordering · 🤖 "Ask AI to Sort" · ↩️ Reset · 💾 Save to chat

flame_graph — Performance Profiler Visualization

Before: Agent receives CPU profile data from an MCP tool → analyzes the JSON and identifies bottlenecks → user sees only the agent's text summary → no way to validate hypotheses or apply domain-specific context.

With MCP Apps: Agent renders an interactive flame graph and can annotate suspected hot paths. User explores the visualization with their own domain knowledge—confirming or rejecting the agent's hypotheses, drilling into areas the agent might have overlooked.

🔍 Click-to-zoom hierarchy · 💬 Hover tooltips · 🧭 Breadcrumb nav · 📊 Send frame to chat

feature_flags — Feature Flag Selector

Before: Agent fetches flag configuration from an MCP tool → summarizes which flags exist and their status → user cross-references with deployment context → asks agent to generate integration code separately.

With MCP Apps: Agent displays a searchable flag picker with live environment status. User selects flags based on their release priorities, switches between prod/staging/dev views, and generates SDK code—agent provides data, user drives decisions.

🌍 Environment tabs · 🔎 Search & filter · ☑️ Multi-select · 📝 Generate SDK code

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run with stdio transport (for Claude Desktop, Cursor, VS Code)
npm run dev

# Or run with HTTP transport (for web-based clients)
npm run dev:http

# Test with MCP Inspector
npm run inspector        # stdio
npm run inspector:http   # HTTP (start server first)

Project Structure

src/
├── index.ts           # Main server (stdio transport)
├── http-server.ts     # HTTP transport variant
└── ui/
    ├── hello-world.ts # Greeting UI template
    ├── list-sort.ts   # Interactive list sorting UI
    ├── flame-graph.ts # Performance flame graph visualization
    └── feature-flags.ts # Feature flag selector UI

MCP Configuration

VS Code

Use the included .vscode/mcp.json:

{
  "servers": {
    "mcp-apps-playground": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Claude Desktop / Cursor

{
  "mcpServers": {
    "mcp-apps-playground": {
      "command": "node",
      "args": ["/path/to/mcp-apps-playground/dist/index.js"]
    }
  }
}

How It Works

1. UI Resource Declaration

UI resources are declared with ui:// scheme and text/html;profile=mcp-app MIME type:

server.resource(
  "greeting-ui",
  "ui://mcp-apps-playground/greeting",
  {
    description: "Interactive greeting UI panel",
    mimeType: "text/html;profile=mcp-app",
  },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/html;profile=mcp-app",
      text: HELLO_WORLD_UI(),
    }],
  })
);

2. Tool with UI Annotation

Tools use _meta.ui.resourceUri to link to a UI resource. Data is passed via structuredContent:

server.registerTool(
  "hello_world",
  {
    description: "Display a Hello World greeting",
    inputSchema: {
      name: z.string().describe("Name to greet"),
    },
    _meta: {
      ui: {
        resourceUri: "ui://mcp-apps-playground/greeting",
        visibility: ["model", "app"],
      },
    },
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
    structuredContent: { name, greeting: `Hello, ${name}!` },
  })
);

3. UI Communication

UIs communicate with the MCP host via postMessage JSON-RPC:

// Initialize handshake (required)
const result = await sendRequest('ui/initialize', {
  protocolVersion: '2025-06-18',
  capabilities: {},
});
sendNotification('ui/notifications/initialized', {});

// Listen for tool data
window.addEventListener('message', (e) => {
  if (e.data.method === 'ui/notifications/tool-input') {
    const { arguments: args } = e.data.params;
    // Update UI with args
  }
});

// Send message to chat
await sendRequest('ui/message', {
  content: [{ type: 'text', text: 'User selected: ...' }]
});

Resources

• MCP TypeScript SDK
• MCP Apps Extension
• MCP Specification
• MCP Inspector

License

MIT