headless-mcp-bridge

# headless-mcp-bridge Scheduled, cron, and other unattended Claude Code runs often cannot use custom MCP servers: the non-interactive session never performs the approval handshake, so the tools silently disappear. This is a config playbook to bridge that gap, with the exact keys and a verify step. ## Why this exists - Reported failure mode: scheduled runs cannot access custom plugins/skills/MCP tools because the unattended session never performs the MCP handshake. Power users want scheduled tasks to use the same MCPs as interactive runs, with tools pre-approved so they are not silently dropped. ## The bridge (do these, in order) ### 1. Register the MCP at USER scope (loads in every session, including headless) ```bash claude mcp add <name> --scope user -- node "C:\\path\\to\\server.js" ``` User-scope servers live in `~/.claude.json` and load in any session, interactive or not, so a scheduled run gets them without a per-project handshake. GOTCHA (learned the hard way): use a command WITHOUT spaces. `node` (on PATH) works; the full path `C:\Program Files\nodejs\node.exe` has a space that can break the spawn and show `Failed to connect`. If you must use a full path, use the 8.3 short form (`C:\PROGRA~1\nodejs\node.exe`). ### 2. Pre-approve project (.mcp.json) servers so unattended runs do not prompt For MCPs defined in a project `.mcp.json`, an unattended run will not stop to approve them. Pre-approve in settings.json: ```jsonc // approve specific servers: "enabledMcpjsonServers": ["<server-a>", "<server-b>"] // or approve all project MCP servers (use deliberately): "enableAllProjectMcpServers": true ``` Keep `disabledMcpjsonServers` for anything you explicitly do NOT want unattended runs to load. ### 3. Verify BEFORE scheduling ```bash claude mcp list # the server must show: ✔ Connected claude mcp get <name> # confirm command + args ``` Only schedule the routine once the server reports Connected. A scheduled run is the wrong place to discover a broken MCP. ### 4. Secrets for unattended runs Headless runs have no one to paste a key. Provide credentials via the server's `env` in the MCP config (or the OS environment the scheduler uses), never inline in a prompt. Keep keys out of git. ## Checklist - [ ] MCP registered at user scope (or pre-approved project server). - [ ] Command has no space-breakage (bare `node` or short path). - [ ] `claude mcp list` shows Connected. - [ ] Secrets supplied via env, not prompt. - [ ] Tested the routine once manually before arming the schedule. ## Composes with - `recall` and other MCP servers: this is how you make them available to scheduled agents. - `mcp-warden`: vet a third-party MCP BEFORE you pre-approve it for unattended use (unattended = higher trust bar). - `schedule` / cron routines: the consumer of this bridge. ## Honest limits - This is configuration + a checklist, not a runtime shim. It does not inject MCP into a runtime that lacks support; it uses the user-scope + pre-approval mechanisms Claude Code already provides. - Behavior can vary by Claude Code version and host (CLI vs desktop vs cloud). Always finish with the `claude mcp list` Connected check on the actual host that will run the schedule.