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

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, 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:

// 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 wraps the Supabase Realtime client to create a private channel per user (user:<user-id>). The createChannel() method configures broadcast acknowledgments and presence tracking:

// 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 starts the local Desktop Commander MCP server—either from 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

// 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:

// 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:

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

Programmatic startup:

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:

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

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

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

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

Key Source Files

File	Purpose
src/remote-device/device.ts	MCPDevice class: orchestration, authentication, tool-call dispatch
src/remote-device/remote-channel.ts	RemoteChannel class: Supabase Realtime, presence, heartbeat, doorbells
src/remote-device/desktop-commander-integration.ts	Local MCP server management and stdio client
src/utils/capture.ts	Telemetry and error forwarding to Supabase logs
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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}