# 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

```bash
# 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:

```json
{
  "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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
- [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
- [MCP Blog Post](http://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/)

## License

MIT