# How the Remote Device Architecture in Desktop Commander MCP Enables Web Access

> Explore the Desktop Commander MCP remote device architecture. Learn how MCPDevice, RemoteChannel, and DesktopCommanderIntegration enable web clients to perform network operations via a persistent Supabase connection.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: architecture
- Published: 2026-08-05

---

**Desktop Commander MCP uses a three-component remote device architecture—`MCPDevice`, `RemoteChannel`, and `DesktopCommanderIntegration`—to maintain a persistent real-time connection to a cloud-hosted Supabase backend, allowing web clients to invoke local tools that can perform network operations.**

The **remote device architecture** in the wonderwhy-er/DesktopCommanderMCP repository transforms any local machine into a web-addressable compute node. By combining Supabase Realtime for signaling, local MCP servers for execution, and robust presence tracking for reliability, users can trigger web-capable tools from any browser without exposing their machine directly to the internet.

## The Three Core Components

The architecture separates concerns across three tightly-coupled TypeScript modules:

### MCPDevice: Lifecycle Orchestrator

Located in [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts), the `MCPDevice` class manages the full lifecycle: authentication, registration, heartbeat scheduling, and tool-call dispatch. It authenticates with Supabase through `DeviceAuthenticator`, persists sessions via `loadPersistedConfig`, and registers the device with its capabilities.

When a web client initiates a request, `MCPDevice.handleNewToolCall()` receives the payload and delegates execution:

```ts
// src/remote-device/device.ts
result = await this.desktop.callClientTool(tool_name, tool_args, metadata);

```

This indirection is what enables **web access to local network capabilities**—the web client never touches the local machine directly.

### RemoteChannel: The Real-Time Bridge

[`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) wraps the Supabase Realtime client to create a private channel per user (`user:<user-id>`). The `createChannel()` method configures broadcast acknowledgments and presence tracking:

```ts
// src/remote-device/remote-channel.ts
this.channel = this.client.channel(channelName, {
    private: true,
    broadcast: { ack: true },
    presence: { key: this.deviceId, enabled: true }
})
.on('broadcast', { event: 'new_call' }, ({ payload }) => this.onDoorbell(payload));

```

The **doorbell pattern** works as follows: the server writes to `mcp_remote_calls` and broadcasts `new_call`. `onDoorbell()` fetches the row, verifies `pending` status, and forwards to `MCPDevice`. Duplicate delivery is prevented through an in-memory `seenCallIds` set plus a conditional DB update (`markCallExecuting`).

### DesktopCommanderIntegration: Local Tool Execution

[`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) starts the local Desktop Commander MCP server—either from [`dist/index.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/dist/index.js) or a globally installed `desktop-commander` CLI—and exposes tools via a **stdio MCP client transport**. This is where web access actually happens: tools like `fetch_url`, headless browsers, or HTTP clients run inside this local process, with results returned through the same chain.

## Persistent Connection and Authentication Flow

Starting a device triggers a five-step sequence:

1. **Load or create session** → `loadPersistedConfig()` checks for existing credentials
2. **Initialize Supabase client** → `RemoteChannel.initialize()` with public URL and anon key from `fetchSupabaseConfig`
3. **Register device** → `RemoteChannel.registerDevice()` writes to `mcp_devices` with `status: "online"` and `capabilities` including `transport_broadcast_v1`
4. **Open private channel** → subscription to `new_call` broadcasts begins
5. **Start adaptive heartbeat** → presence updates maintain reachability

```ts
// src/remote-device/device.ts
await this.remoteChannel.registerDevice(
    await this.desktop.listClientTools(),
    this.deviceId,
    deviceName,
    (payload) => this.handleNewToolCall(payload)
);

```

The `capabilities` payload is critical: it tells the server which transport tier to use and what tools are available for web invocation.

## Adaptive Heartbeat and Presence Tracking

Device reachability relies on regular heartbeats via `RemoteChannel.startHeartbeat()`. The interval adapts to capability:

```ts
// src/remote-device/remote-channel.ts
private heartbeatIntervalMs() {
    return this.transportCapableWritten === true
        ? CAPABLE_HEARTBEAT_INTERVAL   // 5 minutes
        : LEGACY_HEARTBEAT_INTERVAL;   // 15 seconds
}

```

- **Capable devices** (`transport_broadcast_v1: true`): 5-minute heartbeats for efficiency
- **Legacy devices**: 15-second heartbeats for compatibility

If heartbeats stop, the server marks the device offline and stops dispatching calls. This **graceful degradation** ensures web clients receive clear error states rather than hanging requests.

## Exactly-Once Execution Guarantees

The remote device architecture guarantees **exactly-once tool execution** even with unreliable delivery:

- **In-memory deduplication**: `seenCallIds` Set tracks recently processed call IDs
- **Database-level conditional update**: `markCallExecuting` atomically transitions `pending` → `executing` only if still pending
- **Dual transport safety**: The same call may arrive via broadcast and legacy `postgres_changes`; only the first wins

This design permits aggressive retry semantics on the server side without risking duplicate side effects on the client machine.

## Robustness Under Network Stress

Production deployments face socket half-opens, Supabase channel errors, and transient outages. The architecture handles these through:

- **Periodic health checks**: `checkConnectionHealth()` validates channel state and recreates if stuck
- **Exponential backoff with jitter**: `recreateChannel()` prevents stampedes during regional outages
- **Capability withdrawal**: After repeated failures, `transport_broadcast_v1` is revoked, forcing fallback to the legacy transport tier

These mechanisms ensure the **remote device remains reachable from web UIs** through varying network conditions.

## Practical Usage Examples

### Starting a Remote Device

Global installation with session persistence:

```bash
npm install -g @wonderwhy-er/desktop-commander-mcp
desktop-commander-device --persist-session

```

Programmatic startup:

```ts
import { MCPDevice } from './src/remote-device/device.js';

const device = new MCPDevice({ persistSession: true });
await device.start();   // Connects, registers, starts heartbeat

```

### Web Client Tool Invocation Flow

A web UI POSTs to the backend API, which creates a `mcp_remote_calls` row:

```json
{
  "tool_name": "fetch_url",
  "tool_args": { "url": "https://api.example.com/data" },
  "metadata": { "origin": "web" }
}

```

The device receives the doorbell, executes via `DesktopCommanderIntegration.callClientTool()`:

```ts
const result = await this.mcpClient.callTool({
  name: 'fetch_url',
  arguments: { url: 'https://api.example.com/data' },
  _meta: { remote: true }
});

```

Results are written back to the database and broadcast via `result` doorbell for the web client to receive.

### Graceful Shutdown

```ts
await device.shutdown();   // Stops heartbeat, unsubscribes, closes MCP transport
process.exit(0);

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) | `MCPDevice` class: orchestration, authentication, tool-call dispatch |
| [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) | `RemoteChannel` class: Supabase Realtime, presence, heartbeat, doorbells |
| [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) | Local MCP server management and stdio client |
| [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts) | Telemetry and error forwarding to Supabase logs |
| [`src/version.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/version.ts) | Package version for capability payloads |

## Summary

- **Three-component architecture**: `MCPDevice` orchestrates, `RemoteChannel` bridges to Supabase Realtime, `DesktopCommanderIntegration` executes local tools
- **Private real-time channels**: Per-user channels (`user:<user-id>`) enable secure, direct signaling without exposing the host
- **Doorbell pattern with exactly-once delivery**: Broadcast events trigger fetching, with in-memory and database guards against duplicates
- **Adaptive heartbeat**: 5-minute intervals for capable devices, 15-second fallback for legacy support
- **Graceful degradation**: Automatic capability withdrawal and transport fallback maintain connectivity through failures

## Frequently Asked Questions

### How does the remote device know which web client sent a request?

The Supabase `mcp_remote_calls` row includes `user_id` from authenticated sessions. `RemoteChannel` subscribes to channels scoped to that user (`user:<user-id>`), so device-side processing inherently knows the originating user. The `metadata` field can carry additional client context like browser session IDs.

### Can multiple devices serve the same user simultaneously?

Yes. Each device registers independently with its own `deviceId`. The server dispatches calls to all online devices for that user; the first to claim execution (via `markCallExecuting`) handles the request. This provides **load distribution and redundancy** without complex coordination.

### What happens if the local Desktop Commander MCP crashes?

`DesktopCommanderIntegration` monitors the stdio transport. On disconnect, it attempts automatic restart with exponential backoff. Meanwhile, `MCPDevice` continues heartbeating, so the device remains registered but tools return errors until the local server recovers. The web client sees explicit failure rather than timeout.

### Does this architecture work through corporate firewalls?

Yes. The outbound WebSocket connection to Supabase Realtime (typically on port 443) traverses most firewalls without inbound port configuration. No reverse tunnel, VPN, or ngrok-style proxy is required because **all communication initiates from the device to cloud**, with signaling flowing back through the persistent WebSocket.