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

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,6 +33,7 @@
             <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">

frontend/src/types/api.ts

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

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

@@ -96,6 +96,38 @@ 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('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,9 @@ 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)
 	Icon      string // Icon identifier for frontend use
 }
 
@@ -34,8 +35,8 @@ 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.",
 		Icon:      "claude-desktop",
 	},
 	{
@@ -186,6 +187,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,9 @@ 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)
 	Icon       string `json:"icon"`
 	ServerName string `json:"server_name,omitempty"` // name under which mcpproxy is registered
 }
@@ -119,6 +120,7 @@ func (s *Service) GetAllStatus() []ClientStatus {
 			ConfigPath: cfgPath,
 			Supported:  c.Supported,
 			Reason:     c.Reason,
+			Note:       c.Note,
 			Icon:       c.Icon,
 		}
 

internal/connect/connect_test.go

@@ -735,18 +735,146 @@ func TestDisconnect_TOML(t *testing.T) {
 	}
 }
 
-// ---------- Unsupported client tests ----------
+// ---------- Claude Desktop stdio-bridge tests (MCP-2479) ----------
 
-func TestConnect_UnsupportedClient(t *testing.T) {
-	svc, _ := testService(t)
+// Claude Desktop only speaks stdio, so mcpproxy connects via an mcp-remote
+// stdio bridge instead of a direct HTTP/SSE URL. It must be a supported,
+// one-click client.
+func TestClaudeDesktop_SupportedWithBridgeNote(t *testing.T) {
+	client := FindClient("claude-desktop")
+	if client == nil {
+		t.Fatal("expected claude-desktop client definition")
+	}
+	if !client.Supported {
+		t.Error("claude-desktop should be supported via the mcp-remote stdio bridge")
+	}
+	if client.Note == "" {
+		t.Error("claude-desktop should carry a note explaining the mcp-remote bridge")
+	}
+	if !strings.Contains(strings.ToLower(client.Note), "mcp-remote") {
+		t.Errorf("claude-desktop note should mention mcp-remote, got: %q", client.Note)
+	}
+}
 
-	_, err := svc.Connect("claude-desktop", "", false)
-	if err == nil {
-		t.Fatal("Expected error for unsupported client")
+func TestBuildServerEntry_ClaudeDesktop_StdioBridge(t *testing.T) {
+	entry := buildServerEntry("claude-desktop", "http://127.0.0.1:8080/mcp")
+
+	if entry["command"] != "npx" {
+		t.Errorf("expected command=npx, got %v", entry["command"])
+	}
+	args, ok := entry["args"].([]string)
+	if !ok {
+		t.Fatalf("expected args []string, got %T", entry["args"])
+	}
+	want := []string{"-y", "mcp-remote", "http://127.0.0.1:8080/mcp"}
+	if len(args) != len(want) {
+		t.Fatalf("expected args %v, got %v", want, args)
+	}
+	for i := range want {
+		if args[i] != want[i] {
+			t.Errorf("args[%d]=%q, want %q", i, args[i], want[i])
+		}
+	}
+	// A stdio bridge has no direct URL/type fields.
+	if _, ok := entry["url"]; ok {
+		t.Error("stdio-bridge entry should not contain a url field")
+	}
+}
+
+func TestConnect_ClaudeDesktop_WritesStdioBridge(t *testing.T) {
+	svc, homeDir := testService(t)
+
+	cfgPath := ConfigPath("claude-desktop", homeDir)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := svc.Connect("claude-desktop", "", false)
+	if err != nil {
+		t.Fatalf("Connect failed: %v", err)
+	}
+	if !result.Success {
+		t.Fatalf("Expected success, got: %s", result.Message)
+	}
+
+	raw, _ := os.ReadFile(result.ConfigPath)
+	var data map[string]interface{}
+	if err := json.Unmarshal(raw, &data); err != nil {
+		t.Fatalf("Parse config failed: %v", err)
+	}
+
+	servers, ok := data["mcpServers"].(map[string]interface{})
+	if !ok {
+		t.Fatal("Missing mcpServers key")
+	}
+	entry, ok := servers["mcpproxy"].(map[string]interface{})
+	if !ok {
+		t.Fatal("Missing mcpproxy entry")
+	}
+	if entry["command"] != "npx" {
+		t.Errorf("Expected command=npx, got %v", entry["command"])
+	}
+	args, ok := entry["args"].([]interface{})
+	if !ok {
+		t.Fatalf("Expected args array, got %T", entry["args"])
 	}
-	if !strings.Contains(err.Error(), "not supported") {
-		t.Errorf("Expected 'not supported' in error, got: %v", err)
+	want := []string{"-y", "mcp-remote", "http://127.0.0.1:8080/mcp"}
+	if len(args) != len(want) {
+		t.Fatalf("Expected args %v, got %v", want, args)
+	}
+	for i := range want {
+		if args[i] != want[i] {
+			t.Errorf("args[%d]=%v, want %q", i, args[i], want[i])
+		}
+	}
+}
+
+func TestConnect_ClaudeDesktop_BridgeIncludesAPIKey(t *testing.T) {
+	svc, homeDir := testServiceWithKey(t)
+
+	cfgPath := ConfigPath("claude-desktop", homeDir)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := svc.Connect("claude-desktop", "", false)
+	if err != nil {
+		t.Fatalf("Connect failed: %v", err)
+	}
+
+	raw, _ := os.ReadFile(result.ConfigPath)
+	var data map[string]interface{}
+	json.Unmarshal(raw, &data)
+
+	servers := data["mcpServers"].(map[string]interface{})
+	entry := servers["mcpproxy"].(map[string]interface{})
+	args := entry["args"].([]interface{})
+	lastArg, _ := args[len(args)-1].(string)
+	if lastArg != "http://127.0.0.1:8080/mcp?apikey=test-key-123" {
+		t.Errorf("Expected bridge URL with apikey, got %v", lastArg)
+	}
+}
+
+func TestGetAllStatus_ClaudeDesktop_DetectsBridgeConnection(t *testing.T) {
+	svc, homeDir := testService(t)
+
+	cfgPath := ConfigPath("claude-desktop", homeDir)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.Connect("claude-desktop", "", false); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, s := range svc.GetAllStatus() {
+		if s.ID == "claude-desktop" {
+			if !s.Connected {
+				t.Error("expected claude-desktop connected=true after bridge connect")
+			}
+			return
+		}
 	}
+	t.Fatal("claude-desktop status not found")
 }
 
 func TestConnect_UnknownClient(t *testing.T) {
@@ -797,14 +925,15 @@ func TestGetAllStatus(t *testing.T) {
 		t.Errorf("Expected %d statuses, got %d", len(allClients), len(statuses))
 	}
 
-	// Verify claude-desktop is not supported
+	// Verify claude-desktop is supported via the mcp-remote stdio bridge and
+	// surfaces a note explaining the bridge.
 	for _, s := range statuses {
 		if s.ID == "claude-desktop" {
-			if s.Supported {
-				t.Error("claude-desktop should not be supported")
+			if !s.Supported {
+				t.Error("claude-desktop should be supported via the mcp-remote bridge")
 			}
-			if s.Reason == "" {
-				t.Error("claude-desktop should have a reason")
+			if s.Note == "" {
+				t.Error("claude-desktop should expose a bridge note")
 			}
 		}
 	}

internal/httpapi/connect.go

@@ -46,7 +46,7 @@ func (s *Server) handleGetConnectStatus(w http.ResponseWriter, r *http.Request)
 // @Produce     json
 // @Security    ApiKeyAuth
 // @Security    ApiKeyQuery
-// @Param       client path   string         true  "Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)"
+// @Param       client path   string         true  "Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)"
 // @Param       body   body   ConnectRequest false "Optional connection parameters"
 // @Success     200    {object} contracts.APIResponse "ConnectResult"
 // @Failure     400    {object} contracts.ErrorResponse "Bad request"
@@ -108,7 +108,7 @@ func (s *Server) handleConnectClient(w http.ResponseWriter, r *http.Request) {
 // @Produce     json
 // @Security    ApiKeyAuth
 // @Security    ApiKeyQuery
-// @Param       client path   string         true  "Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)"
+// @Param       client path   string         true  "Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)"
 // @Param       body   body   ConnectRequest false "Optional parameters (server_name)"
 // @Success     200    {object} contracts.APIResponse "ConnectResult"
 // @Failure     400    {object} contracts.ErrorResponse "Bad request"

oas/docs.go

@@ -3279,7 +3279,8 @@ paths:
         Remove the MCPProxy entry from the specified client's configuration file.
         Creates a backup of the existing config before modifying.
       parameters:
-      - description: Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)
+      - description: Client ID (claude-code, claude-desktop, cursor, windsurf, vscode,
+          codex, gemini, opencode)
         in: path
         name: client
         required: true
@@ -3327,7 +3328,8 @@ paths:
         Register MCPProxy as an MCP server in the specified client's configuration file.
         Creates a backup of the existing config before modifying.
       parameters:
-      - description: Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)
+      - description: Client ID (claude-code, claude-desktop, cursor, windsurf, vscode,
+          codex, gemini, opencode)
         in: path
         name: client
         required: true