WebRTC MCP Chat Server v2.0

A remote-first WebRTC chat server with secure temporary rooms and full MCP (Model Context Protocol) support, designed for background agents and real-time communication.

✨ New in v2.0: Remote & Secure

🔐 Secure Temporary Rooms - Cryptographically secure, auto-expiring chat rooms
🚀 Remote Deployment Ready - Deploy to Railway, Vercel, Render, Heroku in minutes
🤖 Background Agent Support - Perfect for CI/CD, service coordination, and automation
🛡️ No Local Config Required - Zero-configuration MCP integration
⚡ CLI Tool Included - Command-line interface for agents and scripts

🚀 Quick Start

Install from npm (Recommended)

# Install globally
npm install -g webrtc-mcp-chat

# Create secure temporary room (multiple command options)
webrtc-mcp-chat create --expires 60 --created-by my-agent
# or: chat-room create --expires 60 --created-by my-agent

# Use MCP server with Cursor
webrtc-chat-mcp

Use without installing (npx)

# Create secure temporary room
npx webrtc-mcp-chat create --expires 60 --created-by my-agent

# Use MCP server
npx -p webrtc-mcp-chat webrtc-chat-mcp

For Background Agents (No MCP Config)

# 1. Deploy to remote server (choose one)
npm install -g @railway/cli && railway up
# or: vercel --prod
# or: Connect to Render/Heroku via GitHub

# 2. Set remote server URL
export CHAT_SERVER_URL=https://your-deployed-app.com

# 3. Use the CLI tool for secure communication
chat-room create --expires 60 --created-by my-agent
chat-room join <roomId> <token> <username>
chat-room send <roomId> <token> <username> "Hello secure world!"

For Web Users

Just visit your deployed server URL - no setup required!

For Local Development with Remote Access

# Option 1: ngrok (recommended)
npm run dev:ngrok

# Option 2: Cloudflare Tunnel (free)  
npm run dev:cloudflare

# Option 3: localtunnel (simple)
npm run dev:localtunnel

# Then use the tunnel URL for remote agents
export CHAT_SERVER_URL=https://your-tunnel-url.com
chat-room create --expires 60 --created-by local-agent

For Cursor/MCP Users

After installing globally, add to your MCP configuration:

{
  "mcpServers": {
    "webrtc-chat": {
      "command": "webrtc-chat-mcp",
      "env": {
        "CHAT_SERVER_URL": "https://your-deployed-app.com"
      }
    }
  }
}

Or use without global install:

{
  "mcpServers": {
    "webrtc-chat": {
      "command": "npx",
      "args": ["webrtc-mcp-chat"],
      "env": {
        "CHAT_SERVER_URL": "https://your-deployed-app.com"
      }
    }
  }
}

🎯 Perfect For

🤖 Background agent coordination
🔄 CI/CD pipeline notifications
🔗 Service-to-service communication
⚡ Temporary collaboration channels
🔐 Secure inter-process messaging
📡 Remote system monitoring

🔐 Security Features

256-bit cryptographic tokens for room access
128-bit secure room IDs
Automatic expiration and cleanup (1 hour to 24 hours)
Server-side validation for all operations
No persistent storage - stateless design
Zero-configuration security
Tunnel-ready - Automatic ngrok header support (bypasses browser warnings)
URL normalization - Handles trailing slashes automatically
Comprehensive testing - Built-in tests for header functionality

🌐 Remote Deployment

Deploy to any platform in minutes:

Platform	Command	Notes
Railway	`railway up`	Recommended - includes WebSocket support
Vercel	`vercel --prod`	Serverless deployment
Render	GitHub integration	Auto-deploy from repository
Heroku	`git push heroku main`	Classic platform

See REMOTE_DEPLOYMENT.md for detailed instructions.

🛠️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Users     │    │ MCP/Cursor Users│    │ Background      │
│                 │    │                 │    │ Agents/CLI      │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Video/Audio   │    │ • Text Chat     │    │ • API Calls     │
│ • Screen Share  │    │ • MCP Tools     │    │ • CLI Commands  │
│ • WebRTC P2P    │    │ • Resources     │    │ • HTTP/REST     │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Chat Server    │
                    │  (Remote)       │
                    ├─────────────────┤
                    │ • Socket.IO     │
                    │ • HTTP/REST API │
                    │ • WebRTC Signal │
                    │ • Temp Rooms    │
                    │ • Auto Cleanup  │
                    └─────────────────┘

📋 CLI Commands

The included CLI tool provides everything background agents need:

# Create secure temporary room
chat-room create --expires 120 --created-by agent-1

# Join room with credentials  
chat-room join <roomId> <token> <username>

# Send secure messages
chat-room send <roomId> <token> <username> "Hello world"

# Get room information
chat-room info <roomId> <token>

# Check server health
chat-room health

# Interactive mode for agents
chat-room interactive

🔧 MCP Tools Available

Tool	Description	Use Case
`create_temp_chat`	Create secure temporary room	Agent coordination
`join_temp_chat`	Join temporary room with token	Secure communication
`send_temp_message`	Send message to secure room	Real-time messaging
`get_temp_room_info`	Get room status and users	Monitoring
`check_server_status`	Verify server health	Health checking
`join_public_chat`	Join permanent public room	Long-term collaboration
`send_public_message`	Send to public room	General communication

🚀 Background Agent Examples

Simple Agent Communication

# Agent 1: Create room
ROOM_INFO=$(chat-room create --expires 60 --output json)
ROOM_ID=$(echo $ROOM_INFO | jq -r '.roomId')
ROOM_TOKEN=$(echo $ROOM_INFO | jq -r '.roomToken')

# Agent 2: Join and communicate  
chat-room join $ROOM_ID $ROOM_TOKEN agent-2
chat-room send $ROOM_ID $ROOM_TOKEN agent-2 "Task complete"

CI/CD Integration

#!/bin/bash
# In your pipeline
ROOM_INFO=$(chat-room create --expires 30 --created-by ci-pipeline --output json)
echo "Deployment room: $(echo $ROOM_INFO | jq -r '.joinUrl')"

chat-room send $(echo $ROOM_INFO | jq -r '.roomId') \
              $(echo $ROOM_INFO | jq -r '.roomToken') \
              ci-bot "Deployment started for ${COMMIT_SHA}"

Service-to-Service

// Node.js service
const response = await fetch(`${CHAT_SERVER}/api/create-temp-room`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ expiresInMinutes: 30, createdBy: 'service-a' })
});
const { roomId, roomToken } = await response.json();
// Share credentials with other services

📊 Performance

Room Creation: ~10ms
Message Delivery: ~5ms
Health Checks: ~2ms
Memory per Room: ~1KB
Concurrent Users: 1000+ per instance

🔄 Auto-Scaling

Stateless Design - No database required
Memory-Only Storage - Fast and efficient
Auto-Cleanup - Expired rooms automatically removed
Load Balancer Ready - Health check endpoint included
Multi-Instance - Use sticky sessions for WebSockets

🚨 Monitoring

Health Check Endpoint

curl https://your-app.com/health

Response

{
  "status": "healthy",
  "serverUrl": "https://your-app.com", 
  "remoteMode": true,
  "activeRooms": 5,
  "temporaryRooms": 3,
  "connectedUsers": 12
}

📚 Documentation

REMOTE_DEPLOYMENT.md - Complete deployment guide
LOCAL_REVERSE_PROXY.md - Local server with reverse proxy tunnels
CURSOR_SETUP.md - Cursor IDE integration
Web Interface - Built-in at server root URL
Health Endpoint - /health for monitoring
API Documentation - Available via MCP resources

🛡️ Security Best Practices

Use HTTPS in production deployments
Rotate tokens for long-running agents
Monitor health endpoints regularly
Set appropriate expiration times for rooms
Use environment variables for server URLs
Implement rate limiting if needed

⚡ Quick Deploy Commands

# Railway (Recommended)
railway up

# Vercel  
vercel --prod

# Test deployment
export CHAT_SERVER_URL=https://your-deployed-app.com
chat-room health

# Test ngrok header functionality  
npm run test:ngrok-headers

🤝 Contributing

We welcome contributions! Areas of interest:

Additional deployment platforms
Enhanced security features
Performance optimizations
More CLI commands
Integration examples

📄 License

MIT License - see LICENSE file for details.

Ready to deploy secure, temporary chat rooms for your background agents?

Start with: railway up or vercel --prod

Then: chat-room create --expires 60 --created-by my-agent

🚀 Your agents can now communicate securely!

WebRTC MCP Chat Server