Blog

Headless Claude Code MCP tasks: check capability before scheduling

Check MCP task eligibility before a headless Claude Code run. Use an offline request guard, preserve session input and separate acceptance from completion.

By BringYourSubs4 min read

Before scheduling a headless Claude Code job that needs MCP tasks, verify the session can advertise task support and that your runner will stay connected for the result. A task handle means accepted work, not finished work. Our offline guard checks request metadata before a server chooses a task response; it does not certify a live integration.

Checked 16 November 2026. The five synthetic checks below ran without inference, a subscription login or a live server. Start with Claude-compatible apps, but verify the actual runtime rather than assuming a directory badge guarantees this feature.

Which headless runs are eligible for MCP tasks?

Anthropic's MCP reference requires a task-capable server, supported transport and protocol 2026-07-28, eligible feature flags and a main-conversation call. A one-shot claude -p prompt is excluded. Eligible SDK or stream-JSON input sessions need CLAUDE_AUTO_BACKGROUND_TASKS=1, CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND not 1, and CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS not 0.

Use a preflight record rather than changing flags until a test appears to work. Our suggested fields are the installed version, session surface, transport, negotiated protocol, input lifetime and evidence of request capability. Record unknown values as unknown, not supported.

Observation Suggested preflight verdict What it does not establish
One-shot prompt Choose another lifecycle for task support Whether an ordinary synchronous call could finish
Eligible streaming configuration Candidate for a supervised trial That the feature is enabled for this account
Task extension present in the request Server may consider a task response Completion or permission for external effects
Task extension absent Do not send a task result on that request That retrying unchanged will help
Terminal artifact independently checked Acceptance evidence for that test Reliability of future jobs

The table is our review method, not a replacement for provider negotiation or a production scheduler.

How can a server check the request without calling a model?

The current server-author section documents request capabilities under params._meta["io.modelcontextprotocol/clientCapabilities"], with the task extension in extensions. Return a task only when the request advertises it.

This original JavaScript shape guard is intentionally small:

// task-capability.mjs
function allowsTask(request) {
  const caps = request?.params?._meta?.[
    "io.modelcontextprotocol/clientCapabilities"
  ];
  const ext = caps?.extensions;
  const key = "io.modelcontextprotocol/tasks";
  return Boolean(ext && Object.hasOwn(ext, key) &&
    ext[key] !== null && typeof ext[key] === "object" &&
    !Array.isArray(ext[key]));
}

We tested five synthetic inputs with Node's strict assertions: a present empty extension object, missing metadata, missing extension, a null value and an array value. The guard accepted only the present object. Every assertion passed.

This checks a shape. It does not negotiate a connection, validate the complete protocol, authorize a tool or create a task. Keep a real protocol validator and permission checks outside it. A false result should select a documented ordinary-response path or a clear unsupported-operation error, not secretly start durable work that the client cannot track.

Do not log entire real requests to prove the extension exists. Extract only non-sensitive capability evidence. Arguments and unrelated metadata can contain private material.

What must stay open until the result arrives?

Anthropic's headless guide says a print-mode run does not wait for background MCP work after input closes. A remote task can continue while the client stops following it.

Our proposed runner acceptance test has three separate outcomes: accepted, completed, and inspected. Keep the original session identity with the job record. Do not call a tool again just because the local process exited; first establish what the server already did.

For a supervised trial, use a harmless disposable report. Observe a supported request, capture the task identifier privately, wait for its terminal outcome and inspect the output. Then test your runner's deliberate shutdown and recovery procedure. Do not begin with publishing, purchasing or modifying production data.

Those are tests we recommend before deployment. We did not run that authenticated lifecycle in this writing run, and the offline guard is not evidence that recovery works.

Can bare mode change which account funds the job?

Yes. Anthropic's bare-mode instructions say it skips subscription OAuth credentials and normal auto-discovery. Explicit authentication and configuration need review. Do not add --bare to a subscription workflow as a cosmetic optimization.

Keep two review questions separate: can the job use the feature, and which account pays for the model and tools? Anthropic's legal guidance requires the end user to authenticate their own usage in supported hosted Claude Code arrangements; it does not make a scheduler a reseller of the user's allowance.

Our suggested change record names the old launch mode, proposed mode, intended payer and settings that must remain available. Check that record before approving any authenticated test. Never copy a subscription token into a script or support conversation.

What evidence belongs in the scheduling handoff?

Include the preflight record, synthetic-check output, installed versions, a redacted supervised trial and the inspected artifact. List what has not been tested. Give one operator responsibility for stopping or recovering the job, with the server's own documented procedure available.

Our broader MCP task lifecycle explainer covers durability and cancellation. This page adds the request guard and runner acceptance boundary. If the failure is actually account access, use login diagnosis; if another provider might fund a side task, use the fallback billing audit.

Conductor is one directory entry to investigate for agent workspaces, not a claim that its interface exposes every CLI task feature. Verify the selected surface directly before building unattended work around it.

Questions people ask

Does Claude support MCP tasks in a one-shot run?
Anthropic says a one-shot prompt does not get MCP tasks. Eligible streaming or SDK sessions have additional requirements.
Does an empty tasks capability object mean false?
No. In the documented request shape, the extension can be present as an empty object. Our offline guard accepts that shape.
Does this fixture prove my scheduled agent works?
No. It validates synthetic request shapes only. It does not start Claude Code, contact a server or verify account eligibility.
Is bare mode a subscription-preserving shortcut?
No. Anthropic says bare mode does not read subscription OAuth credentials. Review its authentication requirements before changing a scheduled job.

Sources

  1. Connect Claude Code to tools via MCP, Anthropic, 2026-11-16
  2. Run Claude Code programmatically, Anthropic, 2026-11-16
  3. Legal and compliance, Anthropic, 2026-11-16