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

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

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

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

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

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. The following files define the remote device architecture according to the wonderwhy-er/DesktopCommanderMCP source code:

• src/remote-device/device.ts (source) — Main client class (MCPDevice).
• src/remote-device/remote-channel.ts (source) — JSON-RPC over WebSocket transport (RemoteChannel).
• src/remote-device/device-authenticator.ts (source) — JWT-based authentication workflow (DeviceAuthenticator).
• src/remote-device/desktop-commander-integration.ts (source) — Local MCP server integration and CLI wiring (DesktopCommanderIntegration).
• src/server.ts (source) — 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 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.

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