8.4 KiB

Raw Permalink Blame History

Cremote MCP Multi-Client Support

The Cremote MCP server now supports multiple concurrent clients with isolated browser sessions. This allows multiple AI agents or applications to use the same cremote daemon simultaneously without interfering with each other's browser state.

Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client A      │    │   Client B      │    │   Client N      │
│   (Agent 1)     │    │   (Agent 2)     │    │   (Agent N)     │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │ HTTP/Session         │ HTTP/Session         │ HTTP/Session
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────┴─────────────┐
                    │   Cremote MCP Server      │
                    │   (Session Manager)       │
                    └─────────────┬─────────────┘
                                  │
                                  │ TCP
                                  │
                    ┌─────────────┴─────────────┐
                    │   Cremote Daemon          │
                    │   (Shared Browser)        │
                    └─────────────┬─────────────┘
                                  │
                                  │ DevTools Protocol
                                  │
                    ┌─────────────┴─────────────┐
                    │   Chrome/Chromium         │
                    │   (All tabs accessible)  │
                    └───────────────────────────┘

Transport Modes

1. stdio Transport (Single Client - Legacy)

Default mode - Maintains backward compatibility with existing clients.

# Default mode (stdio)
./cremote-mcp

# Or explicitly set
CREMOTE_TRANSPORT=stdio ./cremote-mcp

Clients: 1 concurrent client
Communication: stdin/stdout JSON-RPC
Session Management: Single global state
Use Case: Existing integrations, single-agent scenarios

2. HTTP Transport (Multiple Clients - New)

Multi-client mode - Supports concurrent clients with session isolation.

# Enable HTTP transport
CREMOTE_TRANSPORT=http ./cremote-mcp

Clients: Multiple concurrent clients
Communication: HTTP POST/GET with JSON-RPC
Session Management: Per-client isolated sessions
Use Case: Multiple agents, concurrent automation

Configuration

Environment Variables

Variable	Default	Description
`CREMOTE_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`CREMOTE_HOST`	`localhost`	Cremote daemon host
`CREMOTE_PORT`	`8989`	Cremote daemon port
`CREMOTE_HTTP_HOST`	`localhost`	HTTP server host (HTTP mode only)
`CREMOTE_HTTP_PORT`	`8990`	HTTP server port (HTTP mode only)

Example Configurations

Single Client (Legacy)

export CREMOTE_HOST=localhost
export CREMOTE_PORT=8989
export CREMOTE_TRANSPORT=stdio
./cremote-mcp

Multiple Clients

export CREMOTE_HOST=localhost
export CREMOTE_PORT=8989
export CREMOTE_TRANSPORT=http
export CREMOTE_HTTP_HOST=localhost
export CREMOTE_HTTP_PORT=8990
./cremote-mcp

Session Management

Session Lifecycle

Initialization: Client sends initialize request, receives Mcp-Session-Id header
Operations: All subsequent requests include the session ID header
Isolation: Each session maintains independent browser state
Cleanup: Sessions auto-expire after 30 minutes of inactivity
Termination: Clients can explicitly terminate sessions with DELETE request

Session State

Each client session maintains isolated state:

Current Tab: Independent active tab tracking
Tab History: Per-client tab navigation history
Iframe Context: Independent iframe mode state
Screenshots: Per-client screenshot collection

Session Headers

HTTP clients must include session headers:

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json
Mcp-Session-Id: a1b2c3d4e5f6g7h8
MCP-Protocol-Version: 2025-06-18

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "web_navigate_cremotemcp",
    "arguments": {
      "url": "https://example.com"
    }
  }
}

Testing Multi-Client Setup

Prerequisites

Start Cremote Daemon:
```
cremotedaemon
```

Start Chrome with Remote Debugging:

chromium --remote-debugging-port=9222 --user-data-dir=/tmp/chromium-debug

Run Multi-Client Test

cd mcp/
./test_multiclient.sh

This test:

Starts the MCP server in HTTP mode
Creates 3 concurrent test clients
Verifies each gets a unique session ID
Tests session isolation
Cleans up all sessions

Manual Testing

Start HTTP Server:
```
CREMOTE_TRANSPORT=http ./cremote-mcp
```

Test with curl:

# Initialize session
curl -X POST http://localhost:8990/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# Use returned Mcp-Session-Id for subsequent requests

Benefits

For AI Agents

Concurrent Operations: Multiple agents can browse simultaneously
State Isolation: No interference between agent sessions
Resource Sharing: Shared browser instance reduces memory usage
Session Recovery: Automatic cleanup prevents resource leaks

For Developers

Scalability: Support multiple concurrent automations
Debugging: Isolated sessions simplify troubleshooting
Flexibility: Choose transport mode based on use case
Compatibility: Backward compatible with existing stdio clients

Limitations

Current Implementation

Tool Coverage: Not all 27 tools are session-aware yet (work in progress)
SSE Streaming: Server-Sent Events not implemented yet
Advanced Features: Some MCP protocol features pending

Planned Improvements

Complete tool migration to session-aware handlers
SSE support for real-time notifications
Enhanced session management features
Performance optimizations

Migration Guide

From Single Client to Multi-Client

Update Environment:

# Old
./cremote-mcp

# New
CREMOTE_TRANSPORT=http ./cremote-mcp

Update Client Code:
- Switch from stdio to HTTP transport
- Handle session ID headers
- Implement proper session cleanup
Test Thoroughly:
- Verify session isolation
- Test concurrent operations
- Monitor resource usage

Backward Compatibility

Existing stdio clients continue to work unchanged:

No code changes required
Same tool interface
Same behavior and performance

Troubleshooting

Common Issues

Session Not Found (404):
- Session expired (30min timeout)
- Invalid session ID
- Server restart cleared sessions
Port Conflicts:
- Change CREMOTE_HTTP_PORT if 8990 is in use
- Ensure cremote daemon port (8989) is available
CORS Issues:
- Server includes CORS headers for web clients
- Use proper Accept headers in requests

Debug Mode

Enable debug logging:

CREMOTE_TRANSPORT=http ./cremote-mcp 2>&1 | tee mcp-debug.log

Next Steps

Complete Tool Migration: Migrate remaining tools to session-aware handlers
Add SSE Support: Implement Server-Sent Events for streaming
Enhanced Testing: Add comprehensive integration tests
Performance Tuning: Optimize session management and cleanup
Documentation: Complete API documentation and examples

8.4 KiB Raw Permalink Blame History