MCP Apps POC

A proof-of-concept demonstrating the MCP Apps Extension (SEP-1865) - the new standard for interactive user interfaces in MCP servers, proposed by Anthropic, OpenAI, and the MCP-UI community.

What is MCP Apps?

MCP Apps allows MCP servers to deliver interactive UIs (HTML/CSS/JS) that render inside AI chat clients. Instead of just returning text, your tools can now show dashboards, forms, charts, and more.

Key features:

• Bidirectional communication: UI can call server tools and send messages back to the chat
• Security sandboxing: UIs run in isolated iframes with controlled capabilities
• Backward compatible: Servers still return text for non-UI-capable clients

Quick Start

# Install dependencies
npm install

# Build everything (MCP app UI + test host)
npm run build

# Run the demo (starts both MCP server and test host)
npm run demo

Then open http://localhost:8080 in your browser.

What's Included

MCP Server (server.ts)

A "Quick Tasks" server with 4 tools:

• get-tasks - Returns task list + renders interactive UI
• add-task - Adds a new task
• toggle-task - Marks tasks complete/incomplete
• delete-task - Removes a task

MCP App UI (src/mcp-app.ts)

Interactive task manager that demonstrates:

• Receiving tool results from the server
• Calling server tools from the UI
• Sending messages back to the chat host
• Dark/light mode support

Test Host (host/)

A React-based host for testing MCP Apps locally. Features:

• Double-iframe sandbox for security isolation
• Server/tool selection UI
• Live tool result display

Architecture

┌─────────────────────────────────────────────────────────┐
│ Test Host (localhost:8080)                              │
│   ┌───────────────────────────────────────────────────┐ │
│   │ Outer iframe (localhost:8081) - sandbox proxy     │ │
│   │   ┌─────────────────────────────────────────────┐ │ │
│   │   │ Inner iframe (srcdoc) - MCP App UI          │ │ │
│   │   │   ┌─────────────────────────────────────┐   │ │ │
│   │   │   │ Quick Tasks App                     │   │ │ │
│   │   │   │ - Renders task list                 │   │ │ │
│   │   │   │ - Calls server tools                │   │ │ │
│   │   │   │ - Sends chat messages               │   │ │ │
│   │   │   └─────────────────────────────────────┘   │ │ │
│   │   └─────────────────────────────────────────────┘ │ │
│   └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                           │
                           │ HTTP (Streamable)
                           ▼
┌─────────────────────────────────────────────────────────┐
│ MCP Server (localhost:3001/mcp)                         │
│   - get-tasks, add-task, toggle-task, delete-task       │
│   - Returns JSON data + ui:// resource URI              │
└─────────────────────────────────────────────────────────┘

Scripts

Command	Description
npm run demo	Start both MCP server and test host
npm run build	Build both MCP app and test host
npm run start	Start MCP server (HTTP mode, port 3001)
npm run start:stdio	Start MCP server (stdio mode)
npm run start:host	Start test host only

Using with Claude Code / Other MCP Clients

For stdio-based MCP clients, add to your config:

{
  "mcpServers": {
    "quick-tasks": {
      "command": "node",
      "args": ["--experimental-strip-types", "/path/to/mcp-apps-poc/server.ts", "--stdio"]
    }
  }
}

Note: Most MCP clients don't support MCP Apps UI rendering yet. The tools will still work but return text-only responses.

Resources

• SEP-1865 Proposal
• MCP Apps SDK
• MCP Blog Post

License

MIT