worker-mcp-free-contexts

Playbook — MCP-free worker contexts

Issue: #2448 Applies to: all p24-infra Claude worker spawns (bms-4, bms-3, vps-i1, dev-laptop)

Why worker contexts are MCP-free

The Supabase MCP server (mcp__claude_ai_Supabase__*) is too heavyweight for dev/CI worker spawns — it adds startup latency and connector auth prompts that a headless worker cannot answer. Every worker node already runs with disableClaudeAiConnectors: true in the claude-runner settings.json, so the MCP was effectively unavailable in worker contexts anyway. Workers do all their Supabase bookkeeping through the REST fallback helpers (supa_upsert / supa_patch / supa_claim_task) — see infra/agent-prompts/worker-issue.md (#1807 / #1888 / #1916).

Out of scope: local dev sessions on Windows (the main Claude Code session) may still use MCP tools. This playbook only governs server-side worker spawns.

The CLAUDE_MCP_DISABLED knob

scripts/spawn-worker.sh and scripts/spawn-infra-task-worker.sh honour a single env var:

Value	Effect
CLAUDE_MCP_DISABLED=1 (default)	Worker claude is launched with --strict-mcp-config (loads zero MCP servers, no config probe). SUPA_MCP_AVAILABLE=0 is forced — REST fallback.
CLAUDE_MCP_DISABLED=0	Legacy behaviour: spawn-worker.sh probes ~/.claude/settings.json for disableClaudeAiConnectors and sets SUPA_MCP_AVAILABLE accordingly. No --strict-mcp-config. Escape hatch for a node that genuinely wires up MCP.

--strict-mcp-config means “only use MCP servers from --mcp-config, ignoring all other MCP configurations” (claude --help). Passing it with no --mcp-config loads nothing — this is the definitive way to stop the worker CLI from probing .mcp.json, user settings, or plugin MCP config.

How SUPA_MCP_AVAILABLE is derived (spawn-worker.sh)

1. CLAUDE_MCP_DISABLED=1 → SUPA_MCP_AVAILABLE=0, MCP_FLAG=--strict-mcp-config (no probe).
2. Else, ~/.claude/settings.json present:
   • disableClaudeAiConnectors: true → SUPA_MCP_AVAILABLE=0.
   • otherwise → SUPA_MCP_AVAILABLE=1.
3. Else (settings.json absent) → SUPA_MCP_AVAILABLE=0 (REST fallback).

**Before 2448 the absent-settings.json branch logged No settings.json found … assuming MCP available and left SUPA_MCP_AVAILABLE=1. That was a false positive — worker contexts have no MCP wired up — and produced the noisy probe warning. It now defaults to the REST fallback.

Audit note (what was checked)

• .mcp.json (repo root) is {"mcpServers": {}} — no MCP servers injected. No change needed.
• Only scripts/spawn-worker.sh contained MCP-probe logic; only it and scripts/spawn-infra-task-worker.sh are dev-worker spawners.
• scripts/run-nightly-triage.sh, scripts/queue-analyst.py, scripts/p24-infra-nightly.sh are separate agent contexts (nightly triage / analyst), not dev-worker spawns — intentionally not changed by #2448.

Verify

bash -n scripts/spawn-worker.sh scripts/spawn-infra-task-worker.sh   # parse check
# With CLAUDE_MCP_DISABLED unset (=1 default) a spawned worker log shows:
#   [mcp] CLAUDE_MCP_DISABLED=1 — worker context is MCP-free; launching claude with --strict-mcp-config …
grep -n 'strict-mcp-config' scripts/spawn-worker.sh scripts/spawn-infra-task-worker.sh