# What Is the Remote MCP Feature and How It Works with ChatGPT and Claude

> Discover Remote MCP and learn how it empowers ChatGPT and Claude to control your local computer securely via WebSocket. Bridge cloud AI with your file system and terminal operations today.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: deep-dive
- Published: 2026-07-20

---

**Remote MCP lets ChatGPT, Claude, or any LLM control your local computer through a secure WebSocket tunnel, bridging cloud AI with local file system and terminal operations.**

The DesktopCommanderMCP repository implements a secure bridge called Remote MCP (Model Context Protocol) that connects cloud-based AI assistants to your local development environment. This feature allows LLMs to execute file system operations, terminal commands, and other local tools remotely while maintaining strict security boundaries. Through a thin Node.js connector running on your machine, Remote MCP forwards authenticated tool calls from ChatGPT or Claude to your local Desktop Commander server.

## Remote MCP Architecture Components

The system relies on five core components that proxy requests securely between cloud AI and your localhost:

- **Remote Device** ([`src/remote-device/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/README.md)): A Node.js connector running locally that opens a WebSocket tunnel to the cloud-hosted Remote MCP service and forwards tool calls to your machine.
- **Remote MCP (cloud service)**: Receives tool calls from the LLM, authenticates sessions, and pushes them through the tunnel to the Remote Device.
- **Local Desktop Commander MCP server** ([`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)): Executes actual file-system, terminal, and tool operations on the host OS.
- **LLM client (ChatGPT/Claude)**: Sends standard MCP tool calls (e.g., `read_file`, `run_command`) which are wrapped with `metadata.remote = true` when traversing the Remote MCP bridge.
- **Capture & Telemetry** ([`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts)): Tags events originating from remote AI using the `captureRemote` helper to distinguish remote from local usage.

## Starting the Remote Device Connector

Install and run the Remote Device globally to establish the connection:

```bash

# Global install (recommended)

npm install -g @wonderwhy-er/desktop-commander

# Run the connector (opens browser for auth)

desktop-commander-device --persist-session   # Keep tokens across restarts

```

The device performs an **OAuth 2.0 Device Authorization Flow** implemented in [`src/remote-device/device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts) to obtain an access token, then establishes a WebSocket connection to the Remote MCP endpoint. The `--persist-session` flag stores credentials locally so you do not need to re-authenticate after restarting your computer.

## How the Secure Tunnel Works

Once authenticated, the connector creates a **Supabase realtime channel** (`RemoteChannel`) that listens for `tool_call` payloads from the cloud. In [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts), the channel handling logic manages reconnection and error logging:

```ts
// src/remote-device/remote-channel.ts (excerpt)
await this.createChannel();               // subscribes to Supabase realtime channel
this.channel!.on('payload', (payload) => {
    // Forward payload to local MCP server
    this.onToolCall?.(payload);
});

```

The **Desktop Commander Integration** ([`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts)) spawns the local MCP server as a stdio child process, injects the `DC_REMOTE_DEVICE=true` environment variable to disable local-only UI elements, and proxies tool calls:

```ts
// src/remote-device/desktop-commander-integration.ts (excerpt)
const result = await this.mcpClient.callTool({
    name: toolName,
    arguments: args,
    _meta: { remote: true, ...metadata }
});

```

## Tool Call Execution Flow from LLM to Local Machine

When ChatGPT or Claude issues a request through the Remote MCP UI (e.g., "read `/etc/hosts`"), the cloud service wraps the request with metadata:

```json
{
  "name": "read_file",
  "arguments": { "path": "/etc/hosts" },
  "_meta": { "remote": true }
}

```

In [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), the CallTool handler extracts `metadata.remote` and sets module-level flags:

```ts
setCurrentCallIsRemote(isRemote);
setCurrentRemoteClient(remoteClientInfo);

```

This makes the server aware that `currentCallIsRemote` is true, enabling proper telemetry attribution. The generic telemetry helper `captureRemote` (exported from [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts)) automatically adds `remote: true` to all captured events, ensuring analytics can filter remote-origin commands.

## End-to-End Workflow Example

Follow these steps to control your local machine remotely via ChatGPT or Claude:

1. **Run the connector**: Execute `desktop-commander-device` and complete OAuth via the provided verification URL and code.
2. **Cloud authentication**: The device opens a WebSocket to Remote MCP and registers itself.
3. **Select device**: In ChatGPT or Claude, open the Remote MCP UI at `https://mcp.desktopcommander.app` and choose your connected device.
4. **Issue commands**: Ask the LLM to read files or run commands. The LLM translates natural language into MCP tool calls.
5. **Local execution**: The call travels through the tunnel to [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts), executes on your machine under your user permissions, and returns results to the chat interface.

## Security and Permission Model

Remote MCP implements strict boundaries to prevent unauthorized system access:

- **Authenticated tunnels**: All connections use short-lived OAuth 2.0 device tokens generated via [`src/remote-device/device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts).
- **User privilege boundaries**: Commands execute under your local user permissions; the remote AI never gains privileged access beyond what your account already possesses.
- **Session control**: Terminate remote access instantly by stopping the device with `Ctrl+C` or disconnecting from the Remote MCP UI.
- **Optional telemetry**: Disable all logging via the `DESKTOP_COMMANDER_DISABLE_TELEMETRY` environment variable if you prefer not to send usage data to analytics.

## Summary

- Remote MCP connects cloud LLMs like ChatGPT and Claude to local Desktop Commander servers via authenticated WebSocket tunnels.
- The **Remote Device** (`src/remote-device/`) handles OAuth authentication in [`device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/device-authenticator.ts) and proxies calls through [`desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/desktop-commander-integration.ts).
- Tool calls originating remotely carry `_meta: { remote: true }`, which [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) detects using `setCurrentCallIsRemote()` and `setCurrentRemoteClient()`.
- The `captureRemote` utility in [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts) ensures proper telemetry attribution for remote-origin commands.
- Security relies on OAuth tokens, user-level permissions, and the `DC_REMOTE_DEVICE` environment flag to disable local-only features.

## Frequently Asked Questions

### What is the Remote MCP feature in DesktopCommanderMCP?

The Remote MCP feature is a secure tunneling system that allows AI assistants like ChatGPT or Claude to execute commands on your local computer. It consists of a Node.js connector (the Remote Device) that runs on your machine and maintains a WebSocket connection to a cloud relay service, forwarding authenticated tool calls from the LLM to your local file system and terminal via the standard Model Context Protocol.

### How does Remote MCP authenticate connections between ChatGPT and my local machine?

Authentication uses the OAuth 2.0 Device Authorization Flow implemented in [`src/remote-device/device-authenticator.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device-authenticator.ts). When you run `desktop-commander-device`, the CLI provides a verification URL and code. After you authenticate in the browser, the device receives an access token that it uses to establish the WebSocket tunnel in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts). All subsequent tool calls are validated through this tokenized session.

### Can I see which commands originated from a remote AI versus local usage?

Yes. When a tool call comes through the Remote MCP tunnel, the cloud service includes `_meta: { remote: true }` in the payload. The server handler in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) sets internal flags via `setCurrentCallIsRemote()`, and the `captureRemote` helper in [`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts) automatically tags telemetry events with `remote: true`. This allows the system to distinguish between local MCP clients and remote ChatGPT/Claude sessions for analytics and debugging.

### Is it safe to run Remote MCP on a production developer workstation?

Remote MCP executes commands under your local user permissions and cannot escalate privileges beyond what your account already has. However, because it allows cloud-based AI to run arbitrary shell commands via `run_command` or read files via `read_file`, you should only connect trusted LLM sessions and terminate the device (`Ctrl+C`) when not actively using the feature. The `DC_REMOTE_DEVICE=true` flag also disables local UI elements like the welcome page to prevent confusion between local and remote control sessions.