--tailscale binds only to the tailnet IP, breaking MCP clients on localhost

[davidg238]

Summary

When server.py is started with --tailscale, it binds only to the node's Tailscale IP and drops the loopback binding. Every place the MCP endpoint is advertised uses http://localhost:<port>/mcp, so an MCP client configured against localhost can never establish the connection — the server shows as perpetually "connecting" and none of its tools surface to the agent. The web viewer and MCP endpoint are effectively unreachable from the same machine over loopback.

Environment

• server.py run as a service with --port 8765 --tailscale
• MCP client (Claude Code) configured with the advertised endpoint http://localhost:8765/mcp

Symptom

• The MCP server is listed but stays in a "connecting" state; tools/list never returns, so tool discovery yields nothing.
• curl -s -X POST http://localhost:8765/mcp -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' returns nothing (connection not served on loopback).
• ss -tlnp shows the listener bound to the tailnet address only, e.g. 100.x.y.z:8765, with no 127.0.0.1:8765.

Root cause

resolve_bind_host() returns the tailnet IP instead of the loopback address when --tailscale is set, and HTTPServer binds to that single address:

def resolve_bind_host(host, use_tailscale, ip_lookup=tailscale_ip):
    if not use_tailscale:
        return host
    ip = ip_lookup()
    if not ip:
        raise ValueError("Could not determine Tailscale IP. ...")
    return ip           # <-- single interface; loopback is dropped

server = HTTPServer((bind_host, port), Handler)   # binds only to bind_host

Meanwhile the endpoint is advertised as loopback in both the UI and docs:

html += 'MCP endpoint: <code ...>http://localhost:' + location.port + '/mcp</code>';

So --tailscale silently relocates the MCP endpoint (and web UI) to the tailnet interface, but nothing that consumes it is told — a same-host MCP client on localhost is left unable to connect.

Reproduction

1. python3 server.py --port 8765 --tailscale
2. Point an MCP client at http://localhost:8765/mcp (as advertised).
3. curl -s -m 3 -X POST http://localhost:8765/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' → no response.
4. ss -tlnp | grep 8765 → bound to 100.x.y.z:8765, not 127.0.0.1.

Suggested fixes (any one)

• Bind loopback in addition to the tailnet IP so --tailscale is additive rather than a move. Simplest: when --tailscale is set, bind 0.0.0.0 (all interfaces, which includes both loopback and the tailnet address) rather than the single tailnet IP — or run two listeners (127.0.0.1 + tailnet IP).
• If a single non-loopback bind is intended, print the actual reachable MCP URL (http://100.x.y.z:8765/mcp) at startup and make the web UI advertise location.host (which it already partially does via location.port) so copy-paste reflects the real bind — and document that MCP clients must use that address, not localhost.
• Consider a startup self-check: after binding, attempt a loopback tools/list and warn if the advertised localhost endpoint isn't actually reachable.

Why it matters

The MCP integration is a headline feature ("any MCP-capable agent can query your entire development history"). With --tailscale, that integration is silently disabled for a local agent, and the failure mode (a server stuck "connecting" with zero tools) gives no hint that the cause is the bind address. In practice an agent falls back to reading ~/.claude/breadcrumbs.db and the raw JSONL directly — which works, but defeats the purpose of the MCP endpoint.

[davidg238]

Refinement: which addresses actually work under --tailscale

Confirmed the server itself is healthy — it responds correctly on its real bind address; this is purely an address-mismatch. Tested against a node running server.py --port 8765 --tailscale:

Client URL	Result
http://localhost:8765/mcp	❌ nothing listening on loopback
http://<bare-hostname>:8765/mcp	❌ bare hostname resolves to the LAN IP (e.g. 192.168.x.y), not the tailnet IP — nothing listening there
http://100.x.y.z:8765/mcp (tailnet IP)	✅ returns the full tools/list
http://<node>.<tailnet>.ts.net:8765/mcp (MagicDNS name)	✅ returns the full tools/list

The gotcha worth calling out: it's not enough to swap localhost for the machine's hostname — the bare hostname typically resolves to the LAN interface, which --tailscale does not bind. The client must use either the MagicDNS name (<node>.<tailnet>.ts.net) or the tailnet IP (100.x.y.z). MagicDNS name is preferable since it survives tailnet IP reassignment and works from other tailnet devices too.

Client-side workaround (no server change): point the MCP registration at the MagicDNS URL. The upstream fix in the issue above (bind 0.0.0.0 so loopback keeps working) remains the better fix since it needs zero client reconfiguration.

[davidg238]

Local workaround applied so this isn't blocking on my end: repointed the MCP client registration to the MagicDNS URL (http://<node>.<tailnet>.ts.net:8765/mcp) instead of localhost. The upstream fix (bind 0.0.0.0 under --tailscale so loopback keeps working, per the issue body) is still the better resolution since it needs zero client reconfiguration and fixes every install, not just this one.

[davidg238]

Corroborated again this session (2026-07-08). The systemd user unit breadcrumbs runs server.py --port 8765 --tailscale, so the live listener is on the tailnet IP only — curl http://localhost:8765/... returns empty, and tests/test_api.sh (which hardcodes localhost, line 49) cannot reach the running instance at all. Dev verification has to target the tailnet IP. No code change here; just noting the workflow impact until the loopback binding is restored (bind both, or keep 127.0.0.1 alongside the tailnet address in resolve_bind_host, server.py:1617).