# Remote Device Architecture for Desktop Commander's Remote MCP Capabilities: Client-Server Model Breakdown

> Explore Desktop Commander's remote device architecture using a client-server model. Learn how the MCPDevice class connects via WebSockets and proxies tool execution to remote processes.

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

---

**Desktop Commander's remote MCP capabilities rely on a thin client-server model where the local MCPDevice class opens a WebSocket JSON-RPC connection to a remote MCP server, authenticates via JWT tokens, and proxies tool execution to sandboxed remote processes.**

The `wonderwhy-er/DesktopCommanderMCP` repository implements a remote device architecture that lets developers execute tools on a remote MCP instance from a local CLI. This architecture enables consistent command execution across local workstations, CI runners, and containerized environments by tunneling JSON-RPC requests over WebSocket connections.

## Core Components of the Remote MCP Architecture

The remote device stack is organized into four primary components that handle connection management, transport, authentication, and CLI integration.

### MCPDevice

Located in [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts), the `MCPDevice` class serves as the high-level entry point for CLI scripts and remote integrations. It reads the `MCP_SERVER_URL` environment variable—defaulting to `https://mcp.desktopcommander.app`—and instantiates a `RemoteChannel` transport to manage the connection. It also drives authentication via `DeviceAuthenticator`.

### RemoteChannel

The `RemoteChannel` class in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) handles the low-level JSON-RPC transport layer. It establishes a WebSocket or HTTP long-poll link to the remote MCP server, marshals requests and notifications, and injects a `clientId` header so the server can identify which remote device originated each call.

### DeviceAuthenticator

Defined in [`src/remote-device/device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts), the `DeviceAuthenticator` manages token-based authentication for the remote device. It exchanges short-lived JWTs with the MCP server, stores tokens in memory, and refreshes them automatically on expiry to maintain an uninterrupted session.

### DesktopCommanderIntegration

The `DesktopCommanderIntegration` module in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) acts as glue code that turns a local Desktop Commander process into an MCP client. It spawns a local MCP server as a child process, wraps its StdIO streams with `CustomStdio`, and wires the `MCPDevice` into the CLI. It also detects Docker-MCP-Gateway mode by checking `process.env.MCP_CLIENT_DOCKER`.

## End-to-End Remote Command Execution Flow

When you run a command such as `desktop-commander run node:local`, the architecture follows this sequence:

1. The CLI invokes `MCPDevice` to create or reuse an existing connection.
2. `MCPDevice` delegates to `RemoteChannel`, which sends a JSON-RPC request with method `start_process` and parameters specifying the tool and arguments.
3. The remote MCP server receives the request, spawns a sandboxed Node process, and streams stdout and stderr events back as JSON-RPC notifications.
4. `RemoteChannel` forwards those notifications to the local CLI, which renders them in the terminal.

Because the transport is JSON-RPC-over-WebSocket, the remote device can be any environment capable of opening a TCP or WebSocket connection, including standard desktops, CI runners, and containers.

## Docker-MCP-Gateway (DXT) Mode

When `process.env.MCP_DXT` is set, the client recognizes that it is running inside a Docker-MCP gateway. In this mode, certain local features such as folder mounting are disabled, but the same JSON-RPC protocol and remote execution flow remain active. You can detect gateway mode at runtime with a simple environment check:

```typescript
if (process.env.MCP_CLIENT_DOCKER === 'true') {
  console.warn('⚠️ Running inside Docker MCP Gateway – limited FS access');
}

```

## Code Examples for Remote MCP Integration

### Creating and Connecting a Remote MCP Device

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

const device = new MCPDevice({
  // Optional: override the default server URL
  serverUrl: 'https://my-custom-mcp.example.com',
  // Persist the auth session across runs (default: false)
  persistSession: true,
});

await device.connect();          // establishes the WebSocket + auth
console.log('✅ Connected to remote MCP');

```

### Running a Tool on the Remote Server

```typescript
// Execute a Node.js REPL on the remote MCP server
const result = await device.runTool('node:repl', {
  args: [],                     // no extra args
  env: { NODE_ENV: 'production' },
});

console.log('Remote REPL PID:', result.pid);

```

### CLI Helper for Remote Execution

```typescript
import { execMcpTool } from './npm-scripts/remote.ts';

await execMcpTool('node:local', ['script.js', '--verbose']);

```

## Key Source Files

All remote MCP logic lives under `src/remote-device/` and integrates with the core server in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts). The following files define the remote device architecture according to the `wonderwhy-er/DesktopCommanderMCP` source code:

- **[`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts)** ([source](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts)) — Main client class (`MCPDevice`).
- **[`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts)** ([source](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts)) — JSON-RPC over WebSocket transport (`RemoteChannel`).
- **[`src/remote-device/device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts)** ([source](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts)) — JWT-based authentication workflow (`DeviceAuthenticator`).
- **[`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts)** ([source](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts)) — Local MCP server integration and CLI wiring (`DesktopCommanderIntegration`).
- **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)** ([source](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)) — Core MCP server that receives remote channel calls and dispatches tools.

## Summary

- The remote device architecture for Desktop Commander's remote MCP capabilities is built on a thin client-server model using JSON-RPC over WebSocket.
- Four primary classes—`MCPDevice`, `RemoteChannel`, `DeviceAuthenticator`, and `DesktopCommanderIntegration`—orchestrate connections, transport, auth, and CLI glue.
- Remote tool execution flows from the local CLI through `MCPDevice` to the remote MCP server, which spawns sandboxed processes and streams output back as JSON-RPC notifications.
- The architecture supports Docker-MCP-Gateway mode via environment variable detection, disabling local filesystem features while preserving protocol compatibility.

## Frequently Asked Questions

### What transport protocol does Desktop Commander use for remote MCP communication?

Desktop Commander uses JSON-RPC over WebSocket with HTTP long-polling as a fallback for all remote MCP communication. The `RemoteChannel` class in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) manages this transport and attaches a `clientId` header to every request so the server can identify the originating device.

### How does the remote device authenticate with the MCP server?

Authentication is handled by the `DeviceAuthenticator` class, which exchanges short-lived JWT tokens with the remote MCP server. The token is stored in memory and refreshed automatically when it expires, ensuring the connection remains valid without manual reauthentication.

### Can Desktop Commander run inside a Docker container?

Yes. The architecture explicitly supports Docker-MCP-Gateway (DXT) mode. When `process.env.MCP_DXT` or `process.env.MCP_CLIENT_DOCKER` is set, the client disables certain local features like folder mounting but continues to use the same JSON-RPC protocol to execute tools remotely.

### What happens when a tool is executed on the remote MCP server?

When the local CLI issues a command, `MCPDevice` sends a JSON-RPC request with method `start_process` to the remote MCP server via `RemoteChannel`. The server spawns a sandboxed process for the requested tool and streams stdout and stderr events back to the local CLI as JSON-RPC notifications.