feat(gateway): remember workspace pins per mcp-remote process

Cursor leaves ${workspaceFolder} unsubstituted on many mcp-remote spawns,
so a session arrives with an empty header and no way to resolve a route.
A manual mcpmux_set_workspace_root fixed only that one session, so every
Reload MCP cost another call.

Pins now promote to a window keyed on the owning process, letting later
sessions from the same mcp-remote inherit the claim. Inheritance is
re-validated against that session's own open folder set, and pins for
dead processes are evicted on read.

Pin logs name their source so a trace can tell a working header from a
manual recovery, and window-pin writes log once per claim instead of once
per request. The bridge snippet and probe recipe inline the access key,
dropping a second substitution that could silently expand to empty.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

Cargo.lock

@@ -1,9 +1,38 @@
 /** Default API-key client name for the global Cursor mcp-remote bridge. */
 export const CURSOR_BRIDGE_CLIENT_NAME = 'cursor-global-bridge';
 
+const DEFAULT_LOOPBACK_PORT = '45818';
+
+/**
+ * Resolve the MCP URL a local `mcp-remote` child should hit.
+ *
+ * The Cursor bridge is stdio on the same machine as the gateway. An advertised
+ * public/tunnel URL (Cloudflare Access) 403s because `mcp-remote` has no Access
+ * cookies. Non-loopback inputs fall back to `127.0.0.1:45818`; a loopback input
+ * keeps its port so a custom local bind still pastes correctly.
+ */
+export function localMcpUrlForCursorBridge(gatewayUrl: string): string {
+  const trimmed = gatewayUrl.trim().replace(/\/$/, '');
+  try {
+    const parsed = new URL(trimmed.includes('://') ? trimmed : `http://${trimmed}`);
+    const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const isLoopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (isLoopback) {
+      const port = parsed.port || DEFAULT_LOOPBACK_PORT;
+      return `http://127.0.0.1:${port}/mcp`;
+    }
+  } catch {
+    // advertised URL or junk — use the default local bind
+  }
+  return `http://127.0.0.1:${DEFAULT_LOOPBACK_PORT}/mcp`;
+}
+
 /**
  * Build the `~/.cursor/mcp.json` snippet for the global mcp-remote bridge.
  *
+ * Always targets loopback (see `localMcpUrlForCursorBridge`) so the snippet is
+ * paste-ready even when the UI is advertising a Cloudflare tunnel.
+ *
  * Cursor resolves `${workspaceFolder}` in `args` at spawn time, so one global
  * entry routes each window to the correct workspace header. That substitution
  * is unreliable (measured at ~21% failure across 282 spawns), and when it
@@ -12,9 +41,17 @@ export const CURSOR_BRIDGE_CLIENT_NAME = 'cursor-global-bridge';
  * `mcp-remote`, which expands it from the child environment — giving the
  * gateway the window's full folder set even when the active folder is missing.
  * The set constrains which root the session may claim; it does not pick one.
+ *
+ * The key is inlined rather than referenced through `env.MCPMUX_API_KEY`. Both
+ * live in this one file at the same permissions, so the indirection bought no
+ * secrecy — only exposure to the same substitution flake: a Cursor MCP respawn
+ * was observed sending the literal `${MCPMUX_API_KEY}`, which the gateway
+ * correctly 401s while the client sits on a connection timeout. The workspace
+ * variables above have to stay variables because they differ per window; a
+ * constant does not.
  */
 export function buildCursorBridgeMcpJson(apiKey: string, gatewayUrl: string): string {
-  const mcpUrl = `${gatewayUrl.replace(/\/$/, '')}/mcp`;
+  const mcpUrl = localMcpUrlForCursorBridge(gatewayUrl);
   const config = {
     mcpServers: {
       mcpmux: {
@@ -29,9 +66,8 @@ export function buildCursorBridgeMcpJson(apiKey: string, gatewayUrl: string): st
           '--header',
           'X-Mcpmux-Workspace-Set:${WORKSPACE_FOLDER_PATHS}',
           '--header',
-          'Authorization:Bearer ${MCPMUX_API_KEY}',
+          `Authorization:Bearer ${apiKey}`,
         ],
-        env: { MCPMUX_API_KEY: apiKey },
       },
     },
   };

apps/desktop/src/features/clients/cursor-bridge-config.helpers.ts

@@ -207,6 +207,6 @@
     "copy": "Copy config",
     "copied": "Copied",
     "keyOnceWarning": "The API key is shown only in this snippet. Store it in ~/.cursor/mcp.json now — McpMux cannot display it again.",
-    "fallbackNote": "Per-repo install via Workspaces remains available if you prefer not to use npx/mcp-remote."
+    "fallbackNote": "The snippet always targets http://127.0.0.1 (local gateway), even when Connections shows a public tunnel. Per-repo install via Workspaces remains available if you prefer not to use npx/mcp-remote."
   }
 }

apps/desktop/src/locales/en/clients.json

@@ -49,6 +49,7 @@ uuid.workspace = true
 chrono.workspace = true
 dashmap = "6.1"
 parking_lot = "0.12"
+netstat2 = "0.11"
 
 # Crypto for OAuth PKCE
 base64 = "0.22"
@@ -73,6 +74,9 @@ oauth2 = "5"
 mcpmux-core.workspace = true
 mcpmux-storage.workspace = true
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
 [dev-dependencies]
 tokio = { workspace = true, features = ["test-util", "macros"] }
 tracing-test = "0.2"