Skip to content

D231 — Local clients get the loopback literal

Decision. The default MCP URL a client is provisioned with is http://127.0.0.1:39273/mcp, derived from the service's default listen address so the two cannot drift. A client config carrying the previous default origin, http://localhost:39273, is read back on 127.0.0.1 with its path kept, and the next connect or sync rewrites every provider's MCP entry from it. Any other URL is left as written.

Why. The service listens on IPv4 loopback only (D112), while clients were told localhost. On Windows localhost resolves to ::1 first, where nothing listens: measured on Windows 11, a .NET request to http://localhost:39273 spent about 2 s falling back to IPv4 against 6 ms for the literal, and a client without a fallback — Kiro CLI, reported in #329 — failed outright. macOS and Linux fall back fast enough to hide it.

Alternatives rejected. Also listening on [::1]:39273: it doubles the listening surface to fix a naming problem. Leaving existing installs to be edited by hand: the broken value was the one Cartographer itself wrote, so Cartographer rewrites it. Rewriting any localhost URL: a user who chose another port or host made a choice, not a default.

Consequences. The migration keys on the exact origin, case-insensitively, and keeps per-KB paths such as /mcp/<kb>. It happens when the client config is loaded, so every command that loads it sees the new URL and the file itself is updated the next time the client saves it.