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

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. 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 (lines 16-34). The constructor reads the server URL from environment variables and instantiates the integration layer.

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 (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 (lines 206-220), the RemoteChannel subscribes to the device_tool_call_queue topic, listening for INSERT events on the tool_calls table.

// 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 (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.

// 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 (lines 42-78). This module maps tool names to concrete OS operations.

// 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 (lines 232-250), the channel updates the corresponding row in the tool_calls table.

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 (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 bootstraps the local daemon that maintains the persistent connection to the backend.
• Device registration occurs in 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, 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 (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 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, 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 (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 (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.

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