From e3336efc251127dd21ef162340435298d134ab78 Mon Sep 17 00:00:00 2001 From: Thomas Nilles Date: Sun, 20 Sep 2026 07:52:31 -0400 Subject: [PATCH] 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 --- AGENT.md | 39 ++++++++++++++++++++++++--------------- CHANGELOG.md | 14 ++++++++++++++ 2 files changed, 38 insertions(+), 15 deletions(-) diff --git a/AGENT.md b/AGENT.md index 7e73898..efc8324 100644 --- a/AGENT.md +++ b/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 - **custom connector**. Like the rest of the app it is **localhost‑bound and - unauthenticated** (Section 0) — do not expose it off‑host without asking. -- **The connector requires `https://`** (Claude Desktop rejects plain `http`). - So `/mcp` is also served over **TLS on localhost** with a **locally‑trusted - cert** (mkcert‑generated; the app just reads the cert/key files). Installing the - local CA into the OS trust store is a **host setup step the user performs**, not - something the app or Claude does (it is a security‑settings change). Do **not** - reach for a public tunnel to get HTTPS — that would expose an unauthenticated - repo‑management app to the internet. + `github.com/modelcontextprotocol/go-sdk`. Like the rest of the app it is + **localhost‑bound and unauthenticated** (Section 0) — do not expose it off‑host. +- **How Claude Desktop connects — the local stdio bridge, NOT the GUI connector.** + The "Add custom connector" GUI is for **remote, publicly‑reachable** servers: + it probes (and would call tools) **from Anthropic's cloud**, which cannot reach + `127.0.0.1`. So a localhost URL there fails "couldn't reach the server" even + though a local browser reaches it. The working path is a **local stdio bridge** + configured in `claude_desktop_config.json` under `mcpServers`, launched on the + user's machine: + ```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 - `https://`**. Resolved with **local TLS via mkcert** — connect to - `https://localhost:8443/mcp` (HTTP dashboard stays on `:8080`). The user runs - `mkcert -install` + cert generation on the host (§8.1); the stdio‑shim fallback - is no longer needed. +- ✅ **RESOLVED 2026-09-20:** Claude Desktop's **GUI "custom connector" cannot + reach a localhost server** — it validates/calls from Anthropic's cloud. Solved + with the **local stdio bridge** (`claude_desktop_config.json` → `mcpServers` → + `mcp-remote http://127.0.0.1:8080/mcp`), §8.1. (HTTPS on `:8443` via mkcert was + 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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5dca79c..07c968d 100644 --- a/CHANGELOG.md +++ b/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.