[hadees]

What

bin/remote-mcp registers a remote, bearer-token MCP server in each Claude Code profile pinned for it, and relays one that lives on a tailnet through a per-server loopback forwarder. It names no server: URL, token references, tailnet and health path all come from machine-local git config (remote-mcp.<server>.*), which the overlays supply. remote-mcp-doctor joins doctor.

Why

claude mcp add covers a public server with a static header. It does not cover a self-hosted one whose token must not sit in a config file and whose host is reachable only over a tailnet the Tailscale app may not be on.

Measured on Claude Code 2.1.296

• claude mcp add-json keeps headersHelper; claude mcp add has no flag for it. connect reads the written entry back.
• The helper may carry arguments and is handed CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CONFIG_DIR, so one helper serves every server and profile.
• The helper gets about ten seconds. Past that the request goes out with no Authorization header and the server answers 401.
• The MCP client honours HTTPS_PROXY, but process-wide: the API connection used it in the same test, and every child process would inherit it. Hence a forwarder per server instead.

Shape

• The token is read from 1Password at connect time and never lands on disk.
• The forwarder is plain HTTP on loopback and TLS to the real name through the tailnet daemon's CONNECT proxy, so the certificate and Host the far side sees are unchanged. It holds no secret, refuses an Origin header or a non-loopback Host, and identifies the config it was started for so a stale one is replaced. headers starts it on demand; nothing is installed or supervised.
• Config is read from the user's git config only, never a checkout's .git/config: these keys decide where a token is sent.
• Unconfigured it is inert on every machine class: one status line, headers fails without calling op, nothing runs at apply.
• The loopback hop assumes a single-user machine, as the tailnet daemons' own loopback proxies do; the script and CLAUDE.md say so.

Also replaces one workset test fixture string with a name from the suite's own vocabulary.

Verified

• bats tests/remote-mcp.bats: 26 tests (stub op/claude/tailnet/curl, sandboxed HOME and git config; the forwarder runs for real against a dead far side)
• End to end against a real server with a throwaway profile: the real CLI ran the helper, the forwarder started on demand and relayed over the tailnet
• Two public-clone review passes and a correctness review; findings folded into the commits
• CI on all four platforms

🤖 Generated with Claude Code