whitelabel-fleet-mcp

MCP server that exposes the whitelabel fleet to remote Claude clients. Plug your iPhone (or another laptop's Claude Desktop) into this and you get the same coding power you have on the host Mac: read/write files, run shell commands, drive git, read whitelabel-memory.

Why

Coding from a phone usually means SSH + a terminal app — passable but clunky, and Claude has no idea what the fleet looks like. Model Context Protocol fixes that: the iOS Claude app speaks MCP as a first-class client, so once this server is exposed, your phone's Claude can call list_dir, git_status, run_shell, etc., as native tools.

Architecture

iPhone Claude
    ↓ HTTPS (Streamable HTTP transport)
Tailscale Serve (or Funnel)
    ↓
127.0.0.1:8473  ← this server
    ↓
Fleet tools:
  • files       read_file, write_file, list_dir, search_code
  • shell       run_shell
  • git         git_status, git_diff, git_log, git_commit
  • memory      read_memory, append_journal

Auth: bearer token in the Authorization header. The token is the perimeter — guard it like a password.

Setup (local)

cd whitelabel-fleet-mcp
npm install
cp .env.example .env
echo "FLEET_MCP_TOKEN=$(openssl rand -hex 32)" >> .env
npm start

Verify:

curl http://127.0.0.1:8473/healthz
# → {"ok":true,"version":"0.1.0","sessions":0}

Full end-to-end smoke test (boots server, runs every tool, prints results):

FLEET_MCP_TOKEN=$(grep FLEET_MCP_TOKEN .env | cut -d= -f2) \
  node scripts/smoke.mjs

Setup (iPhone Claude)

1. Install Tailscale on your iPhone and log in to the same tailnet as the host Mac.
2. On the host Mac, expose the server over HTTPS:

   bash scripts/serve.sh
   

   This prints your tailnet hostname, e.g. https://mac1.tail1234.ts.net/mcp.
3. In the iPhone Claude app:
   • Settings → Connectors → Add custom connector
   • URL: the tailnet /mcp URL from step 2
   • Auth: Bearer token → paste your FLEET_MCP_TOKEN
4. Open a new chat. Claude will list the tools it picked up (read_file, git_status, run_shell, …). Try: "list the whitelabel-flow repo, then show me the most recent commits."

Setup (start at login)

bash scripts/install-launchd.sh

Installs dev.whitelabel.fleet-mcp as a user LaunchAgent that runs at login and restarts on crash. Logs at ~/Library/Logs/whitelabel-fleet-mcp/{stdout,stderr}.log.

Uninstall:

launchctl unload ~/Library/LaunchAgents/dev.whitelabel.fleet-mcp.plist
rm ~/Library/LaunchAgents/dev.whitelabel.fleet-mcp.plist

Tools

Tool	What it does
read_file	Read a UTF-8 file (up to 1 MB).
write_file	Create or overwrite a file. Makes parent dirs.
list_dir	List immediate children of a directory.
search_code	rg (or grep -r) across the workspace.
run_shell	Execute a shell command via zsh -lc. Capped at 600 s and 200 KB output.
git_status	git status --short --branch for any repo.
git_diff	Unstaged or staged diff, optionally narrowed to paths.
git_log	Last N commits, oneline.
git_commit	Stage + commit, with optional push.
read_memory	Fetch whitelabel-memory/HANDOFF.md + most-recent journal.
append_journal	Drop a new journal entry into whitelabel-memory.

All file/repo paths must resolve inside WORKSPACE_ROOT (set in .env, default ~/Documents). Paths outside are rejected.

Security notes

• The bearer token is the only auth. Rotate it if you suspect leakage.
• run_shell runs anything — gating is intentional only against Cloudflare/Tailscale-level mishaps, not the authenticated client. If you give the token to a friend they can do anything you can.
• Tailscale Serve binds to your tailnet only; Funnel would expose it to the public internet (HTTPS-auth'd by token, not network ACL). Prefer Serve unless you need outside access.

Roadmap

Version	Adds
v0.1 (here)	core tools, bearer auth, Tailscale Serve, LaunchAgent
v0.2	dispatch_to_worker (call whitelabel-orchestrator API to fire long-running jobs on mac1-4)
v0.3	summon_claude_code (spawn a fleet claude -p for heavy refactors)
v0.4	per-tool ACLs (some clients get read-only, some can shell)
v1.0	replaces dispatch.sh entirely as the fleet's RPC layer