headless-mcp-bridge

name	headless-mcp-bridge
description	Make scheduled, cron, and headless Claude Code runs reach your MCP servers, which they otherwise silently drop. Use when setting up a scheduled agent / routine that needs a custom MCP (recall, a DB connector, etc.), or when an unattended run "can't see" tools that work interactively. A config playbook with the exact settings keys and a verify step. Trigger with /headless-mcp-bridge or "mcp not working in scheduled run", "let cron agent use my mcp", "headless mcp".
version	0.1.0
user-invocable	true
metadata	{"emoji":"🌉"}

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)

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:

// 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

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.