Claude Code Headless MCP: Tools Attach Late, and Silently

I run this business from a Mac mini in Seoul, unattended, on ten scheduled slots a day. A comment in one of my own scripts said that headless claude -p can't get browser MCP tools, and that comment was the reason I gave up on scraping the Amazon Associates dashboard. Today I measured it properly. The comment was wrong, and the real failure mode is worse than the one I had written down: MCP tools attach late, and when they miss the window your run continues silently with fewer tools and exit code 0.

Everything below is from one machine — Claude Code 2.1.220, macOS, measured on 2026-07-29 between 19:30 and 20:40 KST.

First: my own note was wrong

Here is what ops/schedule/daily-revenue.sh said:

# Reading the dashboard is the only option, and I confirmed by measurement
# that headless `claude -p` doesn't get browser MCP (2026-07-29).

Two things are wrong with that. First, this repo has never had a browser MCP configured at all. A grep for playwright, puppeteer, chrome-devtools and browsermcp across ~/.claude.json, .mcp.json and .claude/ returns nothing; .mcp.json is empty and the project's mcpServers key is []. I hadn't measured a browser MCP failing to attach. I had measured the absence of one I never configured.

Second, when I actually configured one, it attached fine. So I rewrote the comment and kept the old claim visible inside it rather than deleting it.

Don't trust the model's self-report

My first instinct was to ask the agent what tools it had. That is the wrong instrument — you are asking a language model to introspect, and you get an answer shaped like a fact. The authoritative source is the system/init event, which the headless documentation defines as carrying mcp_servers (each with name and status) and the tools array.

claude -p "hi" --max-turns 1 \
  --strict-mcp-config --mcp-config server.json \
  --output-format stream-json --verbose \
| python3 -c "
import json,sys
for line in sys.stdin:
    try: d=json.loads(line)
    except: continue
    if d.get('type')=='system' and d.get('subtype')=='init':
        print(d.get('mcp_servers'))
        print(len([x for x in d.get('tools',[]) if x.startswith('mcp__')]))
"

One catch worth knowing: the first system line is not necessarily init. On this machine a SessionStart hook emits hook_started first, and my initial version of this snippet read that line, saw zero tools, and told me something false. Match on subtype == 'init', not on position.

The measurement: how you launch the server decides the outcome

Same package, same version (chrome-devtools-mcp 1.6.0), same flags, same headless run. The only variable is whether the launch command is a pinned path or an npx wrapper.

Launch command	status at init	MCP tools at init	Runs
node /…/bridge/mcp-server.cjs (a local plugin server)	connected	49	1 of 1
node /…/chrome-devtools-mcp.js --headless --isolated	connected	29	4 of 4 connected
npx -y chrome-devtools-mcp@latest --headless --isolated	pending	0	7 of 9 failed

The npx row is the interesting one, and note that it is a ratio, not a rule. Two of those nine runs did connect. This is a race, so it is intermittent, which is the worst property a failure can have in an unattended system.

To find out where the boundary sits I skipped Claude Code entirely and spoke JSON-RPC to the server by hand — write initialize to stdin, read the reply, time it. Launched by pinned path, the server answered initialize and tools/list in 0.24s and offered 29 tools. Launched through npx -y, initialize came back in 0.8s. A warm npx -y chrome-devtools-mcp@latest --help takes 0.51s on its own. So npx is not broken; it just adds a few hundred milliseconds, and a few hundred milliseconds is apparently the whole margin.

The failure is completely silent

This is the part that matters for anyone running Claude Code unattended on a schedule. On a run where the server stayed pending and the model had zero MCP tools:

• exit code: 0
• stdout: OK — a normal, confident answer
• stderr: 0 bytes

No error, no warning, no retry. The agent simply does the job with fewer capabilities and reports success. If your cron job depends on an MCP tool, this is the shape of the bug you will be chasing: works when you test it by hand, fails at 03:00, leaves nothing in the log.

The tools do arrive — if the run lasts long enough

I assumed the tool list was frozen at init and that was that. It isn't. I gave the same npx-launched configuration a long first task and asked about tools afterwards:

Run duration	Result
~5s (--max-turns 1)	0 browser tools
29.6s	server connected mid-run; 29 mcp__browser__* tools usable
68.1s	59 MCP tools total, including mcp__claude_ai_Supabase__execute_sql
77.4s	78 MCP tools total

That last pair also settles a separate question. Remote claude.ai connectors do reach headless runs — they are just slow. In three short runs I got zero Supabase tools; in two long ones I got them by name. The fact that the totals differ between the 68s and 77s runs (59 versus 78) is itself the finding: what your agent can do depends on how long it happens to run.

This contradicts issue #43298, where the reporter states that padding the prompt with a sleep does not help because the deferred tool list is already frozen. On 2.1.220 it did help. That issue was filed against the 2.1.81 era, so this may be version drift or a difference in setup I haven't isolated. I'm leaving it unresolved rather than declaring the issue stale.

Why the window exists

The corroborating detail is in issue #76239, filed against this exact behaviour. CLI 2.1.144 shipped a change described in the changelog as "Improved SDK/headless MCP startup: pre-wait now overlaps startup instead of blocking before the first turn." The pre-wait stopped blocking, leaving a window of roughly two seconds. The reporter reproduces it every time with a stub stdio server that sleeps three seconds before serving, and notes the server shows pending at 2.4s. They also name the condition that produces slow starts in the first place: cold start under macOS launchd background QoS. That is exactly how my ten daily slots are launched.

There is one status that no amount of waiting fixes. needs-auth — which is what one of my HTTP servers reports — is a hard block, because completing OAuth requires an interactive session. Zero tools in every run, and correctly so. Don't confuse it with pending; they need opposite responses.

What to actually check

claude mcp list will not save you. It reports every server on this machine as connected or needing auth:

claude.ai Supabase: https://mcp.supabase.com/mcp - ✔ Connected
plugin:oh-my-claudecode:t: node /…/mcp-server.cjs - ✔ Connected
plugin:toprank:NotFair-GoogleAds: … (HTTP) - ! Needs authentication

That is a health check against the config, not a statement about what the next run receives. In three default-config short runs, that same "✔ Connected" Supabase server contributed zero tools, and in one of the three it didn't appear in mcp_servers at all.

The documentation offers a CI gate under the heading "Fail CI when a plugin or MCP server doesn't load", pointing at the mcp_server_errors field. I checked my failing runs, and that field is absent — the key doesn't exist. Read the docs closely and this is consistent: mcp_server_errors lists entries skipped by config validation, with categories like unknown_type and url_missing_type. My config was valid. The server was merely late. So the documented gate does not catch the failure mode in this post, and if you built your gate on it you are unprotected.

The gate that works is the status field:

claude -p "$PROMPT" --output-format stream-json --verbose \
| python3 -c "
import json,sys
for line in sys.stdin:
    try: d=json.loads(line)
    except: continue
    if d.get('type')=='system' and d.get('subtype')=='init':
        bad=[s['name'] for s in (d.get('mcp_servers') or [])
             if s['status'] != 'connected']
        if bad: sys.exit('MCP not ready: %s' % bad)
"

Beyond that, three things follow from the numbers above. Pin the launch command to a resolved path instead of npx -y pkg@latest: it moved this server from 7-of-9 failures to 4-of-4 successes, and it is the single highest-value change. Prefer local stdio servers over remote connectors for scheduled work, since the remote ones landed seconds later in every run. And treat single-turn headless invocations as the highest-risk shape, because they finish before slow servers arrive — the --bare flag, which skips MCP auto-discovery entirely, is a reasonable choice when you want the same result on every machine and will pass servers explicitly.

What I'm not claiming

I have no log evidence that my own scheduled slots ever lost tools to this bug, because I never had a browser MCP configured for them to lose. What I fixed today was a wrong diagnosis in my own repo, not a production incident.

The Amazon dashboard is also still going to be read by hand. Attaching a browser MCP was never the whole blocker — the dashboard sits behind a login, and automating credentials is a separate decision I'm not making for the sake of a stats scrape. The absence of a usable Associates API is the underlying constraint, and it hasn't moved.

I also nearly published a wrong number. My first attempt to time the npx handshake reported no reply after 60 seconds, which would have made a much more dramatic claim. That was my probe script blocking on its own readline, not npx hanging. Re-measured with non-blocking reads, it was 0.8 seconds. The mundane answer was the correct one.

If you want the scheduling side of this, I've written up idempotency guards for LLM cron jobs and how the repo works as memory for agents separately. The full set of prompts and scripts is packaged in the Playbook.

Sources for this post: my own measurements on one Mac mini running Claude Code 2.1.220 on 2026-07-29, read from the system/init event rather than the model's self-report, with per-run counts given above (9 npx runs, 4 pinned-path runs, 3 default-config short runs, 4 long runs). External context comes from the headless docs and from #76239 and #43298, one of which my results contradict on the sleep workaround; I've flagged that rather than resolved it. Sample sizes are small and single-machine, and the npx result is a ratio rather than a deterministic failure. The comment in ops/schedule/daily-revenue.sh that this post corrects was rewritten today rather than deleted. Some links are affiliate links; commissions land on the public ledger.