WebRTC MCP Chat Server

A remote WebRTC chat server with secure temporary rooms and MCP support for background agents.

GitHub

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:

PlatformCommandNotes
Railwayrailway upRecommended - includes WebSocket support
Vercelvercel --prodServerless deployment
RenderGitHub integrationAuto-deploy from repository
Herokugit push heroku mainClassic 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

ToolDescriptionUse Case
create_temp_chatCreate secure temporary roomAgent coordination
join_temp_chatJoin temporary room with tokenSecure communication
send_temp_messageSend message to secure roomReal-time messaging
get_temp_room_infoGet room status and usersMonitoring
check_server_statusVerify server healthHealth checking
join_public_chatJoin permanent public roomLong-term collaboration
send_public_messageSend to public roomGeneral 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

  1. Use HTTPS in production deployments
  2. Rotate tokens for long-running agents
  3. Monitor health endpoints regularly
  4. Set appropriate expiration times for rooms
  5. Use environment variables for server URLs
  6. 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!

Serveurs connexes