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

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

# 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 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, the channel handling logic manages reconnection and error logging:

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

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

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

In src/server.ts, the CallTool handler extracts metadata.remote and sets module-level flags:

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) 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, 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.
• 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 and proxies calls through desktop-commander-integration.ts.
• Tool calls originating remotely carry _meta: { remote: true }, which src/server.ts detects using setCurrentCallIsRemote() and setCurrentRemoteClient().
• The captureRemote utility in 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. 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. 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 sets internal flags via setCurrentCallIsRemote(), and the captureRemote helper in 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.

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