# How Remote MCP Enables Web-Based AI Clients to Access Local Resources

> Discover how Remote MCP uses Supabase Realtime WebSockets to let web AI clients like ChatGPT execute local shell commands and access files securely via an HTTP API.

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

---

**Remote MCP establishes a secure WebSocket bridge via Supabase Realtime, allowing browser-based AI models to execute local shell commands and file operations through an HTTP API.**

Remote MCP (implemented in the wonderwhy-er/DesktopCommanderMCP repository) eliminates the network barrier between cloud AI services and local machines. By deploying a lightweight local daemon that maintains a persistent connection to a realtime backend, this architecture grants web clients like ChatGPT controlled access to native OS resources without requiring browser extensions or direct localhost access.

## The Remote MCP Architecture

Remote MCP operates on a **bridge pattern** that separates the web-facing API from local execution. The system consists of three core components: the **MCPDevice** daemon running locally, a **Supabase Realtime** backend routing messages, and an **HTTP API server** defined in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts). This design bypasses CORS restrictions and mixed-content limitations that typically prevent web applications from accessing localhost services.

## Bootstrapping the Local MCP Device

Connection initialization begins with the `MCPDevice` class in [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) (lines 16-34). The constructor reads the server URL from environment variables and instantiates the integration layer.

```typescript
import { MCPDevice } from './remote-device/device.js';

(async () => {
  const device = new MCPDevice({ persistSession: true });
  await device.start(); // Boots Supabase client, registers device, opens realtime channel
})();

```

The `start()` method orchestrates authentication and channel subscription, creating a persistent bridge ready to receive remote commands from any web-based AI client.

## Authentication and Device Registration

Before processing commands, the device authenticates with Supabase using JWT access tokens. In [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 58-70), the client establishes a session, then the `registerDevice()` method (lines 155-176) creates or updates a record in the `mcp_devices` table.

This registration stores the generated `device_id` locally and ensures only authenticated devices can subscribe to the user's private command queue, preventing unauthorized access to local resources.

## Real-Time Communication via Supabase

The core innovation lies in the **Supabase Realtime** WebSocket subscription. In [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 206-220), the `RemoteChannel` subscribes to the `device_tool_call_queue` topic, listening for INSERT events on the `tool_calls` table.

```typescript
// Inside RemoteChannel.registerDevice
this.channel = this.client.channel('device_tool_call_queue')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'tool_calls' }, 
    payload => {
      if (this.onToolCall) this.onToolCall(payload.new);
    })
  .subscribe();

```

When a web AI client posts a request, Supabase broadcasts the payload instantly to the connected local device, enabling sub-second latency for command execution.

## Sending Requests from Web-Based AI Clients

Web clients interact with the system through the stateless HTTP API in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 78-95). The server accepts POST requests to `/api/tool-call`, validates the JWT authorization header, and inserts a record into the `tool_calls` table.

```typescript
// AI client (e.g., ChatGPT) sending request
await fetch('https://mcp.desktopcommander.app/api/tool-call', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${userJwt}` },
  body: JSON.stringify({
    device_id: '<device-id-from-registration>',
    tool: 'shell',
    args: { command: 'ls -l ~/Documents' }
  })
});

```

This **stateless HTTP design** allows any web-based AI capable of making HTTP requests to trigger local actions without native SDKs or browser plugins.

## Executing Local Tools

Upon receiving a realtime payload via the `onToolCall` callback, the device delegates execution to `DesktopCommanderIntegration` in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) (lines 42-78). This module maps tool names to concrete OS operations.

```typescript
// From desktop-commander-integration.ts
async handleToolCall(call) {
  switch(call.tool) {
    case 'shell': return await this.executeShell(call.args);
    case 'readFile': return await this.readLocalFile(call.args.path);
    case 'openBrowser': return await this.openUrl(call.args.url);
  }
}

```

The integration abstracts platform-specific implementations, enabling AI clients to request actions like "read file" or "execute command" without understanding underlying OS differences.

## Returning Results to the AI

After execution completes, the device propagates results back through Supabase. In [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 232-250), the channel updates the corresponding row in the `tool_calls` table.

```typescript
await this.client.from('tool_calls')
  .update({ result: executionResult, status: 'completed' })
  .eq('id', callId);

```

The web-based AI client polls `GET /api/tool-call/:id` to retrieve the completed result, allowing the model to incorporate local command outputs into its conversational responses.

## Connection Resilience and Health Monitoring

Production deployments require handling network interruptions. The `RemoteChannel` class in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 279-311) implements automatic reconnection logic that monitors socket state and recreates the channel on disconnect while maintaining the device's online status flag.

This ensures temporary Wi-Fi drops or machine sleep cycles do not permanently sever the bridge between web AI and local resources.

## Summary

- **Remote MCP** creates a secure bridge between browser-based AI and local machines using Supabase Realtime WebSockets and JWT authentication.
- The **MCPDevice** class in [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) bootstraps the local daemon that maintains the persistent connection to the backend.
- **Device registration** occurs in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts), storing credentials in the `mcp_devices` table for secure session isolation.
- Web clients send commands through the **stateless HTTP API** in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), which writes to the `tool_calls` table to trigger realtime events.
- **DesktopCommanderIntegration** maps tool requests to OS-level actions like shell commands, file I/O, and browser operations.
- **Bidirectional communication** allows local execution results to flow back to web-based AI clients, enabling closed-loop interactions with local resources.

## Frequently Asked Questions

### How does Remote MCP authenticate web-based AI clients to ensure only authorized users access local resources?

Remote MCP uses **Supabase JWT authentication** implemented in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 58-70). Each device must present valid access tokens to register in the `mcp_devices` table and subscribe to the private `device_tool_call_queue` topic. The HTTP API in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) validates these tokens on every request, ensuring only authenticated sessions matching the device's registered user can insert tool calls into the queue.

### Can Remote MCP work with AI services other than ChatGPT?

Yes. Because Remote MCP exposes a **standard HTTP API** in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), any web-based AI capable of making POST and GET requests can integrate with the system. This includes Claude, custom GPT implementations, or proprietary assistants. The AI client simply needs to authenticate with the user's JWT and reference the correct `device_id` obtained during device registration to invoke local tools through the bridge.

### What happens when the local device loses internet connectivity?

The `RemoteChannel` class implements robust **reconnection logic** in [`src/remote-device/remote-channel.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/remote-channel.ts) (lines 279-311) that monitors WebSocket state and automatically recreates subscriptions when connectivity returns. While offline, tool calls remain in the `tool_calls` table with a "pending" status. Upon reconnection, the device processes queued commands and updates results, allowing AI clients to poll asynchronously for completion without losing request context.

### Which local operations can web-based AI clients perform through Remote MCP?

Through the **DesktopCommanderIntegration** module in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) (lines 42-78), AI clients can execute shell commands, read and write files, open URLs in the default browser, and perform other OS-level actions. The tool contract abstracts these capabilities behind JSON payloads, allowing AI models to request complex local workflows without understanding platform-specific implementations across macOS, Windows, or Linux.