How Remote MCP Enables Cloud AI Access to Your Local Computer

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, 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 exposes the runRemote() function, which bootstraps the entire remote session. This function parses the --remote flag, loads Supabase credentials from config.json, and delegates to the high-level wrapper in 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 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, 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:

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

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

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

# Launch the remote client

desktop-commander --remote

This executes the runRemote() function in 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:

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:

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

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: Core Realtime channel, session handling, heartbeat, and reconnection logic.
• 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: CLI entry point for the --remote mode.
• src/utils/capture.ts: Telemetry helper adding the remote: true flag to analytics events.
• 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 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, 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.

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