MCP React UI Server

This example features a complete MCP (Model Context Protocol) remote server with UI capabilities using React and React Router V7. The server provides both text-based and interactive UI tools that can be used with MCP-compatible clients like Claude Desktop.

🚀 Features

• MCP Protocol Support: Implements the Model Context Protocol with 4 interactive tools
• Interactive UI Tools: Provides rich visualizations for task status and user profiles
• React Router 7: Full-stack routing with server-side rendering
• Session Management: Handles multiple concurrent MCP sessions
• UI Resources: Returns interactive UIs using @mcp-ui/server instead of plain text
• TypeScript: Full type safety throughout the codebase
• Tailwind CSS 4: Modern styling framework

🛠️ Tech Stack

• Core Framework: React Router 7, React 19, TypeScript, Vite
• MCP Integration: @mcp-ui/server, @modelcontextprotocol/sdk
• UI Libraries: Recharts for data visualization, Tailwind CSS for styling
• Server: Express.js with React Router integration

📋 MCP Tools

The server provides 4 MCP tools:

1. get_user_profile - Returns user data as text
2. get_tasks_status - Returns textual task status summary for all team members
3. show_task_status - Displays an interactive task dashboard UI with:
   • Team task status visualization
   • Zoom capability by team member
   • Interactive charts with tooltips
4. show_user_status - Shows user profile with:
   • Performance metrics and charts
   • Task completion statistics
   • Blocked tasks with priority indicators
   • Nudge functionality

🚀 Getting Started

Prerequisites

• Node.js 18 or higher
• pnpm package manager

Installation

1. Clone the repository
2. Install dependencies:

   pnpm install
   

Development

To run the server in development mode:

pnpm dev

The server will start on port 80 by default (configurable via VITE_PORT environment variable).

Production

To build and run the server in production mode:

pnpm build
pnpm start

Quick start

To build and run the server in docker container:

docker build -t mcp-server-react-ui -f Dockerfile.app.prod . && docker run --rm -p 3001:3001 mcp-server-react-ui

🔧 Configuration

Environment Variables

• VITE_PORT - Port for the development server (default: 3001)
• VITE_HMR_PORT - Port for Hot Module Replacement (default: same as VITE_PORT)

📁 Project Structure

/mcp-server-react-ui/
├── express-server/
│   ├── index.ts                # Main Express server 
│   ├── handlers.ts             # MCP request handlers
│   └── tools.ts                # MCP tool definitions
├── react-router-server/
│   └── index.ts                # React Router SSR setup
├── app/
│   ├── root.tsx                # React Router root layout
│   ├── routes.ts               # Route definitions
│   ├── routes/
│   │   ├── home.tsx            # Home route
│   │   ├── task.tsx            # Task status visualization route
│   │   └── user.tsx            # User profile route
│   ├── graph/
│   │   └── graph.tsx           # Task status graph component
│   └── user/
│       └── user.tsx            # User profile component
├── public/                     # Static assets (avatars)
├── package.json
├── vite.config.ts
├── react-router.config.ts

🔍 Core Concepts

UI Resources

The server uses createUIResource from @mcp-ui/server to return interactive UIs instead of plain text:

const resourceBlock = createUIResource({
  uri: `ui://task-manager/${Date.now()}` as `ui://${string}`,
  content: { type: 'externalUrl', iframeUrl: pickerPageUrl },
  encoding: 'text',
});

Session Management

The server implements session-based transport management:

• Each MCP session is tracked using unique session IDs
• Transport instances are stored in memory using a map
• Each session has its own StreamableHTTPServerTransport instance

Server-Side Rendering

The application uses React Router with server-side rendering:

• Express integrates with React Router via react-router/express
• UI routes are rendered on the server for better performance

📊 Sample Data

The task status tools work with sample sprint data:

{
  alice: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
  bob: { remaining: 18, toDo: 11, inProgress: 4, blocked: 3 },
  charlie: { remaining: 14, toDo: 6, inProgress: 5, blocked: 3 }
}

🔌 Integration Points

• MCP Client: Connects via /mcp endpoints
• Claude Desktop: Can invoke tools and display UI resources
• React Components: Rendered at /task and /user routes
• UI Components: Interactive charts and user profiles with message passing to parent

🤝 Contributing

Contributions, ideas, and bug reports are welcome! Feel free to check issues or create a new one.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

💡 About MCP-UI

mcp-ui brings interactive web components to the Model Context Protocol (MCP). It allows you to deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client, taking AI interaction to the next level!

For more information about MCP-UI, visit the official documentation.

🚀 Supported Hosts

MCP-UI is supported by a growing number of MCP-compatible clients. Feature support varies by host:

• Nanobot - Full rendering and UI actions support
• Postman - Rendering with partial UI actions
• Goose - Rendering with partial UI actions
• LibreChat - Rendering with partial UI actions