MCP Apps POC

# 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