feat(connect): one-click Claude Desktop via mcp-remote stdio bridge (MCP-2479) (#682)

* feat(connect): one-click Claude Desktop via mcp-remote stdio bridge

Claude Desktop was marked unsupported in the Connect wizard because it
only speaks stdio, even though mcpproxy can be reached from it via an
`npx -y mcp-remote <mcpURL>` bridge (already documented in docs/setup.md).

- Flip claude-desktop to Supported=true and add a stdio-bridge branch to
  buildServerEntry that writes `command: npx`, `args: [-y, mcp-remote, <mcpURL>]`.
- Add a Note field (ClientDef/ClientStatus) surfacing the bridge requirement;
  render it in ConnectModal so users know the path uses mcp-remote (needs Node.js).
- Connected-state detection already matches the canonical `mcpproxy` entry name,
  so bridge connections are tracked without a URL field.
- Docs: note the one-click wizard path in docs/setup.md; widen connect POST/DELETE
  client-ID examples.

Related MCP-2479

* test(connect): isolate claude-desktop config path on Windows

On Windows, ConfigPath ignores the homeDir override for claude-desktop
and vscode (it reads %APPDATA%), so the no-key and with-key Claude Desktop
bridge tests both wrote to the same real APPDATA\Claude path. The no-key
test ran first and created the entry; the with-key test then hit
`already_exists` (force=false) and never wrote the apikey, failing the
assertion on the windows-amd64 runner.

Pin %APPDATA% under the per-test temp dir in the test-service helpers,
mirroring the existing %LOCALAPPDATA% line, so every client's config path
is isolated per-test on Windows. No-op on macOS/Linux.

Related MCP-2479

* fix(connect): bridge connectable on fresh install + detect custom-name bridge

Addresses Codex REQUEST_CHANGES on PR #682 (MCP-2479):

Gap 1 — Connect button hidden on fresh installs. A fresh Claude Desktop has
no config file yet (exists=false), so the modal showed "Config not found"
instead of a Connect button even though Connect can create the file. Add a
`Bridge` flag to ClientDef/ClientStatus (true for claude-desktop) and relax
the frontend gate to `supported && (exists || bridge)` for the button and
the Connect-All set.

Gap 2 — Status detection only matched the `mcpproxy` key. A bridge written
under a custom server_name has no URL field and a non-default key, so it
showed disconnected. Detect the bridge by inspecting the entry args
(mcp-remote + mcpURL) via entryPointsToBridge, regardless of the key.

Tests: custom-name bridge detection, bridge flag on ClientDef/status, and a
fresh-install (exists=false) Connect-button render. go test ./internal/connect/...
green; full vitest + vue-tsc green.

Related MCP-2479

Author: Dumbris

docs/setup.md

@@ -254,6 +254,8 @@ Add mcpproxy as a remote MCP server via Settings → Connectors → Add Custom C
 
 #### Option A: Free Plan — JSON Configuration
 
+> **💡 One-click:** mcpproxy's built-in **Connect** wizard (Web UI / tray) can write this bridge configuration for you automatically — pick **Claude Desktop** and click **Connect**. It registers the `npx -y mcp-remote` bridge shown below (Node.js required). The manual steps remain available if you prefer to edit the file yourself.
+
 1. Create the config file if it doesn't exist:
 
 **macOS:**

frontend/src/components/ConnectModal.vue

@@ -33,11 +33,12 @@
             <div class="min-w-0 flex-1">
               <div class="font-medium text-sm truncate">{{ client.name }}</div>
               <div class="text-xs opacity-50 truncate" :title="client.config_path">{{ client.config_path }}</div>
+              <div v-if="client.note" class="text-xs opacity-60 italic mt-0.5" :title="client.note">{{ client.note }}</div>
             </div>
           </div>
           <div class="shrink-0 ml-2">
             <span v-if="!client.supported" class="badge badge-ghost badge-sm">{{ client.reason || 'Not supported' }}</span>
-            <span v-else-if="!client.exists" class="text-xs opacity-40">Config not found</span>
+            <span v-else-if="!client.exists && !client.bridge" class="text-xs opacity-40">Config not found</span>
             <button
               v-else-if="client.connected"
               @click="disconnect(client.id)"
@@ -114,7 +115,9 @@ const loading = reactive({
 })
 
 const connectableClients = computed(() =>
-  clients.value.filter(c => c.supported && c.exists && !c.connected)
+  // Bridge clients (e.g. Claude Desktop) can be connected even without an
+  // existing config file — Connect creates it.
+  clients.value.filter(c => c.supported && (c.exists || c.bridge) && !c.connected)
 )
 
 const allConnected = computed(() =>

frontend/src/types/api.ts

@@ -795,6 +795,8 @@ export interface ClientStatus {
   connected: boolean
   supported: boolean
   reason?: string
+  note?: string
+  bridge?: boolean
   icon: string
   server_name?: string
 }

frontend/tests/unit/connect-modal.spec.ts

@@ -96,6 +96,69 @@ describe('ConnectModal', () => {
     expect(wrapper.text()).toContain('⌘')
   })
 
+  it('renders a Connect button and bridge note for Claude Desktop', async () => {
+    ;(api.getConnectStatus as any).mockResolvedValue({
+      success: true,
+      data: [{
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        config_path: '/Users/test/Library/Application Support/Claude/claude_desktop_config.json',
+        exists: true,
+        connected: false,
+        supported: true,
+        note: 'Connects via an mcp-remote stdio bridge (npx -y mcp-remote). Requires Node.js.',
+        icon: 'claude-desktop',
+      }],
+    })
+
+    const wrapper = mount(ConnectModal, {
+      props: { show: false },
+      global: { plugins: [pinia] },
+    })
+
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    // A real one-click Connect button must be offered (not greyed out).
+    const connectButton = wrapper.find('button.btn-primary.btn-xs')
+    expect(connectButton.exists()).toBe(true)
+    expect(connectButton.text()).toContain('Connect')
+
+    // The bridge note must be surfaced to the user.
+    expect(wrapper.text()).toContain('mcp-remote stdio bridge')
+  })
+
+  it('shows Connect for a bridge client even when its config file does not exist', async () => {
+    ;(api.getConnectStatus as any).mockResolvedValue({
+      success: true,
+      data: [{
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        config_path: '/Users/test/Library/Application Support/Claude/claude_desktop_config.json',
+        exists: false,
+        connected: false,
+        supported: true,
+        bridge: true,
+        note: 'Connects via an mcp-remote stdio bridge (npx -y mcp-remote). Requires Node.js.',
+        icon: 'claude-desktop',
+      }],
+    })
+
+    const wrapper = mount(ConnectModal, {
+      props: { show: false },
+      global: { plugins: [pinia] },
+    })
+
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    // Fresh install: no config file yet, but the bridge Connect must still appear.
+    const connectButton = wrapper.find('button.btn-primary.btn-xs')
+    expect(connectButton.exists()).toBe(true)
+    expect(connectButton.text()).toContain('Connect')
+    expect(wrapper.text()).not.toContain('Config not found')
+  })
+
   it('disconnect uses server_name alias when OpenCode status is adopted', async () => {
     ;(api.getConnectStatus as any).mockResolvedValue({
       success: true,

internal/connect/clients.go

@@ -14,8 +14,10 @@ type ClientDef struct {
 	Name      string // Human-readable name, e.g. "Claude Code"
 	Format    string // File format: "json" or "toml"
 	ServerKey string // Top-level key for server entries: "mcpServers" or "servers"
-	Supported bool   // Whether this client supports HTTP/SSE transport
+	Supported bool   // Whether this client can be connected (directly or via a bridge)
 	Reason    string // Explanation when Supported is false
+	Note      string // Optional caveat shown for supported clients (e.g. bridge requirement)
+	Bridge    bool   // Connects via a stdio bridge; Connect can create the config when absent
 	Icon      string // Icon identifier for frontend use
 }
 
@@ -34,8 +36,9 @@ var allClients = []ClientDef{
 		Name:      "Claude Desktop",
 		Format:    "json",
 		ServerKey: "mcpServers",
-		Supported: false,
-		Reason:    "Claude Desktop only supports stdio transport; HTTP/SSE not available",
+		Supported: true,
+		Note:      "Connects via an mcp-remote stdio bridge (npx -y mcp-remote). Requires Node.js.",
+		Bridge:    true,
 		Icon:      "claude-desktop",
 	},
 	{
@@ -186,6 +189,13 @@ func buildServerEntry(clientID, mcpURL string) map[string]interface{} {
 			"type": "http",
 			"url":  mcpURL,
 		}
+	case "claude-desktop":
+		// Claude Desktop only speaks stdio, so bridge to mcpproxy's HTTP
+		// endpoint with mcp-remote run via npx.
+		return map[string]interface{}{
+			"command": "npx",
+			"args":    []string{"-y", "mcp-remote", mcpURL},
+		}
 	case "cursor":
 		return map[string]interface{}{
 			"url":  mcpURL,

internal/connect/connect.go

@@ -31,8 +31,10 @@ type ClientStatus struct {
 	ConfigPath string `json:"config_path"`
 	Exists     bool   `json:"exists"`           // config file exists on disk
 	Connected  bool   `json:"connected"`        // mcpproxy entry present in config
-	Supported  bool   `json:"supported"`        // client supports HTTP/SSE
+	Supported  bool   `json:"supported"`        // client can be connected (directly or via a bridge)
 	Reason     string `json:"reason,omitempty"` // why not supported
+	Note       string `json:"note,omitempty"`   // caveat for supported clients (e.g. bridge requirement)
+	Bridge     bool   `json:"bridge,omitempty"` // connects via a stdio bridge; connectable even without an existing config
 	Icon       string `json:"icon"`
 	ServerName string `json:"server_name,omitempty"` // name under which mcpproxy is registered
 }
@@ -119,6 +121,8 @@ func (s *Service) GetAllStatus() []ClientStatus {
 			ConfigPath: cfgPath,
 			Supported:  c.Supported,
 			Reason:     c.Reason,
+			Note:       c.Note,
+			Bridge:     c.Bridge,
 			Icon:       c.Icon,
 		}
 
@@ -670,6 +674,13 @@ func (s *Service) findEntryJSON(client ClientDef, cfgPath string) (string, bool)
 			}
 		}
 
+		// Stdio-bridge clients (e.g. Claude Desktop) have no URL field; the
+		// mcpproxy endpoint lives in the command args. Detect by inspecting
+		// args so a bridge written under a custom server name is still found.
+		if entryPointsToBridge(entry, mcpURL, baseURL) {
+			return name, true
+		}
+
 		// Also match by server name
 		if name == defaultServerName {
 			return name, true
@@ -679,6 +690,30 @@ func (s *Service) findEntryJSON(client ClientDef, cfgPath string) (string, bool)
 	return "", false
 }
 
+// entryPointsToBridge reports whether a JSON config entry is an mcp-remote
+// stdio bridge targeting our MCP endpoint, regardless of the entry key.
+func entryPointsToBridge(entry map[string]interface{}, mcpURL, baseURL string) bool {
+	rawArgs, ok := entry["args"].([]interface{})
+	if !ok {
+		return false
+	}
+	hasBridgePkg := false
+	pointsToUs := false
+	for _, a := range rawArgs {
+		s, ok := a.(string)
+		if !ok {
+			continue
+		}
+		if s == "mcp-remote" {
+			hasBridgePkg = true
+		}
+		if s == mcpURL || s == baseURL || strings.HasPrefix(s, baseURL+"?") {
+			pointsToUs = true
+		}
+	}
+	return hasBridgePkg && pointsToUs
+}
+
 var trailingCommaPattern = regexp.MustCompile(`,\s*([}\]])`)
 
 func unmarshalLenientJSON(raw []byte, out interface{}) error {