Correct Claude Desktop connection: local stdio bridge, not GUI connector

The GUI custom-connector flow validates/calls from Anthropic's cloud and can't reach a localhost server, so a 127.0.0.1 URL fails there. The working path is a local mcp-remote stdio bridge configured in claude_desktop_config.json pointing at http://127.0.0.1:8080/mcp. Updated AGENT.md 8.1/11 and CHANGELOG. HTTPS on :8443 stays available but optional.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

AGENT.md

@@ -342,16 +342,25 @@ obeys the safety rules (§1.4).
 ### 8.1 MCP server — Claude drives the app (`internal/mcp`)
 
 - The app serves an **MCP endpoint over Streamable HTTP at `/mcp`** using
-  `github.com/modelcontextprotocol/go-sdk`. Claude Desktop connects to it as a
+  `github.com/modelcontextprotocol/go-sdk`. Like the rest of the app it is
-  **custom connector**. Like the rest of the app it is **localhost‑bound and
+  **localhost‑bound and unauthenticated** (Section 0) — do not expose it off‑host.
-  unauthenticated** (Section 0) — do not expose it off‑host without asking.
+- **How Claude Desktop connects — the local stdio bridge, NOT the GUI connector.**
-- **The connector requires `https://`** (Claude Desktop rejects plain `http`).
+  The "Add custom connector" GUI is for **remote, publicly‑reachable** servers:
-  So `/mcp` is also served over **TLS on localhost** with a **locally‑trusted
+  it probes (and would call tools) **from Anthropic's cloud**, which cannot reach
-  cert** (mkcert‑generated; the app just reads the cert/key files). Installing the
+  `127.0.0.1`. So a localhost URL there fails "couldn't reach the server" even
-  local CA into the OS trust store is a **host setup step the user performs**, not
+  though a local browser reaches it. The working path is a **local stdio bridge**
-  something the app or Claude does (it is a security‑settings change). Do **not**
+  configured in `claude_desktop_config.json` under `mcpServers`, launched on the
-  reach for a public tunnel to get HTTPS — that would expose an unauthenticated
+  user's machine:
-  repo‑management app to the internet.
+  ```json
+  "gitmanager": { "command": "cmd",
+    "args": ["/c","npx","-y","mcp-remote","http://127.0.0.1:8080/mcp"] }
+  ```
+  `mcp-remote` runs locally and speaks stdio to Claude Desktop, so it reaches the
+  local endpoint directly and needs **no public exposure and no HTTPS**. Do **not**
+  reach for a public tunnel — that would expose an unauthenticated repo‑management
+  app to the internet.
+- **HTTPS is still available** (`:8443`, mkcert cert) for clients that require it,
+  but is not needed for the stdio‑bridge path above.
 - MCP **tools are thin adapters** over the service layer — no Git/forge logic in
   the tool handlers (§1.7). Expected tools (grow as features land):
   - Read: `list_repos`, `get_repo`, `get_active_project`, `get_activity`,
@@ -514,11 +523,11 @@ silently guess.)*
 - ✅ **RESOLVED 2026-09-19:** **Project handoff is cooperative** — user requests a
   switch, Claude finishes to a safe checkpoint, switches, and the user is notified;
   pull‑first, not autonomous (Section 8.3).
-- ✅ **RESOLVED 2026-09-20:** Claude Desktop's custom connector **requires
+- ✅ **RESOLVED 2026-09-20:** Claude Desktop's **GUI "custom connector" cannot
-  `https://`**. Resolved with **local TLS via mkcert** — connect to
+  reach a localhost server** — it validates/calls from Anthropic's cloud. Solved
-  `https://localhost:8443/mcp` (HTTP dashboard stays on `:8080`). The user runs
+  with the **local stdio bridge** (`claude_desktop_config.json` → `mcpServers` →
-  `mkcert -install` + cert generation on the host (§8.1); the stdio‑shim fallback
+  `mcp-remote http://127.0.0.1:8080/mcp`), §8.1. (HTTPS on `:8443` via mkcert was
-  is no longer needed.
+  added earlier and still works, but is not required for this path.)
 - **Idle‑trigger for handoff:** the pull model syncs at Claude's turn boundaries.
   If Claude is idle when the user switches, decide the nudge (user's next message,
   a heartbeat/poll, or a host push if available) — do not assume instant wake.

CHANGELOG.md

@@ -84,3 +84,17 @@ Append-only running history of all changes (AGENT.md §9.1). Newest last.
   `.gitignore`, `.env.example`, `AGENT.md` (§8.1, §11).
 - **Host setup (user-run):** the local CA install (`mkcert -install`) is a
   security-settings change performed by the user, not the app.
+
+## 2026-09-20 — Connect Claude Desktop via local stdio bridge (mcp-remote)
+- **What:** Corrected the Claude Desktop connection method in AGENT.md (§8.1, §11).
+  The GUI "Add custom connector" flow can NOT reach a localhost server — it probes
+  and calls tools from Anthropic's cloud, so `https://127.0.0.1:8443/mcp` fails
+  "couldn't reach the server" even though a local browser reaches it. The working
+  path is a local stdio bridge in `claude_desktop_config.json`:
+  `mcpServers.gitmanager = cmd /c npx -y mcp-remote http://127.0.0.1:8080/mcp`.
+  Added that entry to the user's Claude Desktop config (backup saved alongside).
+- **Why:** Keep the app localhost-only + unauthenticated (§0) while still letting
+  Claude Desktop drive it. `mcp-remote` runs locally, so it reaches the local
+  endpoint directly — no public exposure, no HTTPS needed for this path.
+- **Affects:** `AGENT.md` (§8.1, §11); user's `claude_desktop_config.json` (outside
+  the repo). HTTPS/`:8443` from the prior entry stays available but is now optional.