# How Remote MCP Enables Cloud AI Access to Your Local Computer

> Discover how Remote MCP securely connects cloud AI to your local computer via Supabase Realtime. Enable AI agents to run tools directly on your machine through database triggers.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-14

---

**Remote MCP establishes a secure bi-directional bridge between cloud AI models and your local machine using Supabase Realtime, allowing AI agents to execute tools on your computer by inserting database rows that trigger immediate local execution.**

The DesktopCommanderMCP repository implements Remote MCP (Mobile-Control-Protocol) to let cloud-based AI services like OpenAI, Anthropic, Claude, and Gemini interact with your local file system and applications. This architecture eliminates the need for direct network tunneling by using Supabase as a secure message broker, enabling real-time tool execution through a simple database-driven command queue.

## Core Architecture Components

Remote MCP operates through three integrated layers that authenticate your local client, maintain persistent connectivity, and translate database events into executable commands.

### Supabase Backend

The **Supabase** service acts as the central hub, storing device records in the `mcp_devices` table and queuing remote commands in the `mcp_remote_calls` table. It provides a persistent WebSocket channel via Supabase Realtime, enabling push-style communication between cloud AI services and your local machine without requiring open ports on your network.

### RemoteChannel Class

Located in **[`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts)**, the `RemoteChannel` class wraps the Supabase Realtime client to handle authentication, device registration, and event listening. The Supabase client initializes in `RemoteChannel.initialize()` at **lines 58-60**, creates a channel subscription to `postgres_changes` on the `mcp_remote_calls` table at **lines 21-23**, and forwards incoming payloads to the registered `onToolCall` callback at **lines 19-21**. It also maintains a 15-second heartbeat to update the `last_seen` timestamp on your device record and triggers automatic reconnection via `recreateChannel()` if the channel stalls.

### Desktop Commander Remote Runner

The entry point **[`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts)** exposes the `runRemote()` function, which bootstraps the entire remote session. This function parses the `--remote` flag, loads Supabase credentials from [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json), and delegates to the high-level wrapper in **[`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts)**. At **lines 101-105**, `runRemote()` instantiates `RemoteChannel`, authenticates the session, registers the device, and enters the tool-execution loop.

## End-to-End Execution Flow

When a cloud AI needs to access your computer, Remote MCP orchestrates the following sequence:

1. **Startup**: You launch the remote client with `desktop-commander --remote`. The CLI loads the Supabase URL and API key from [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) and calls `RemoteChannel.initialize()`.

2. **Authentication**: `RemoteChannel.setSession()` sends your OAuth access and refresh tokens to Supabase via `auth.setSession`, storing the returned user object as `this._user`.

3. **Device Registration**: `RemoteChannel.registerDevice()` either locates an existing record or creates a new entry in `mcp_devices` containing your user ID, device name, and `online` status.

4. **Realtime Subscription**: `RemoteChannel.createChannel()` opens a Realtime channel on the `device_tool_call_queue` topic. Supabase pushes any INSERT operation on `mcp_remote_calls` matching your user ID directly to the client through the `postgres_changes` listener.

5. **Tool Call Handling**: When the cloud AI inserts a row into `mcp_remote_calls`, your local client receives the payload immediately. The `onToolCall` callback executes the requested tool locally, then calls `RemoteChannel.updateCallResult()` to write the result (or error) back to the same database row.

6. **Heartbeat and Health Checks**: Every 15 seconds, the client updates the `last_seen` field on its device record. If the channel remains in the `joining` state too long, the client automatically triggers `recreateChannel()` to restore connectivity.

7. **Telemetry**: All remote events are logged via `captureRemote()` in **[`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts)**, adding a `remote: true` flag to distinguish cloud-initiated calls from local execution.

## Implementation Details

### Initializing the Supabase Connection

The `RemoteChannel` class establishes the database connection immediately upon startup:

```typescript
// From src/remote-device/remote-channel.ts (lines 58-60)
initialize(supabaseUrl: string, supabaseKey: string) {
  this._supabase = createClient(supabaseUrl, supabaseKey);
  // ... additional setup
}

```

### Authenticating and Registering Devices

Device registration binds your local machine to your user account and prepares the callback handler for incoming commands:

```typescript
// From src/remote-device/device.ts (lines 101-105)
await channel.setSession({
  access_token: process.env.SUPABASE_ACCESS_TOKEN!,
  refresh_token: process.env.SUPABASE_REFRESH_TOKEN!
});
await channel.registerDevice(
  capabilities,
  deviceId,
  deviceName,
  onToolCall
);

```

### Handling Realtime Tool Calls

The subscription mechanism listens for database changes and routes them to your execution handler:

```typescript
// From src/remote-device/remote-channel.ts (lines 21-23)
this._channel.on('postgres_changes', 
  { event: 'INSERT', schema: 'public', table: 'mcp_remote_calls' },
  (payload) => this._onToolCall(payload)
);

```

## Practical Code Examples

### Starting Remote MCP from the CLI

Launch the remote client to begin accepting cloud AI commands:

```bash

# Launch the remote client

desktop-commander --remote

```

This executes the `runRemote()` function in **[`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts)**, which initializes the channel and begins listening for tool calls.

### Registering a Device with Callback Handling

Register your device and define how incoming tool calls should be processed:

```typescript
await remoteChannel.registerDevice(
  { /* capability object */ },
  existingDeviceId,
  'My-Laptop',
  async (payload) => {
    // payload.new contains the remote call details
    const result = await executeTool(payload.new);
    await remoteChannel.updateCallResult(
      payload.new.id, 
      'completed', 
      result
    );
  }
);

```

### Cloud-Side Tool Call Insertion

From the cloud AI service, trigger a local action by inserting a command:

```javascript
// Server-side pseudo-code
await supabase
  .from('mcp_remote_calls')
  .insert({
    user_id: userId,
    tool_name: 'open_file',
    args: { path: '/home/user/report.pdf' },
    status: 'queued'
  });

```

### Updating Execution Results

After local execution completes, write the result back to the database:

```typescript
await remoteChannel.updateCallResult(callId, 'completed', {
  output: 'File opened successfully',
  exit_code: 0
});

```

## Key Files in the Remote MCP Implementation

- **[`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts)**: Core Realtime channel, session handling, heartbeat, and reconnection logic.
- **[`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts)**: High-level wrapper that authenticates, registers the device, and bridges tool calls to the channel.
- **[`src/npm-scripts/remote.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/npm-scripts/remote.ts)**: CLI entry point for the `--remote` mode.
- **[`src/utils/capture.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts)**: Telemetry helper adding the `remote: true` flag to analytics events.
- **[`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts)**: Utility used during channel recreation to prevent operation hangs.

## Summary

- **Remote MCP** uses Supabase Realtime as a secure message broker, eliminating the need for direct network access to your local machine.
- 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 authentication, device registration, and bi-directional communication through database change events.
- Cloud AI agents execute local tools by inserting rows into `mcp_remote_calls`, which trigger immediate local execution via the `onToolCall` callback.
- A 15-second heartbeat and automatic channel recreation ensure reliable connectivity even through network interruptions.
- All remote operations are logged with the `remote: true` flag via `captureRemote()` for audit and debugging purposes.

## Frequently Asked Questions

### What security mechanism prevents unauthorized cloud AI access?

Remote MCP requires OAuth authentication via `RemoteChannel.setSession()` before any device registration occurs. The Supabase row-level security policies ensure that only authenticated users can insert into or query from `mcp_remote_calls` and `mcp_devices`, and the local client only responds to commands matching your specific user ID.

### How does Remote MCP handle connection interruptions?

The client implements a 15-second heartbeat that updates the `last_seen` field on your device record. If the Realtime channel stalls in the `joining` state, the `recreateChannel()` method automatically tears down and rebuilds the connection using the timeout utility in [`src/utils/withTimeout.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/withTimeout.ts), ensuring continuous availability without manual intervention.

### What is the difference between local and remote MCP execution?

Local execution runs tools directly on your machine without cloud interaction, while remote execution uses the `RemoteChannel` to listen for database events. Remote calls are tagged with `remote: true` in the telemetry system via `captureRemote()`, allowing the backend to distinguish between local tool usage and cloud-initiated commands for monitoring and rate-limiting purposes.

### Which cloud AI providers are compatible with Remote MCP?

Any cloud AI service capable of writing to a Supabase database can integrate with Remote MCP, including OpenAI's GPT models, Anthropic's Claude, Google's Gemini, and custom AI agents. The protocol is provider-agnostic because it relies on standard SQL INSERT operations into the `mcp_remote_calls` table rather than proprietary APIs.