Skip to main content
Glama
icey2488

claude-async

by icey2488
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

claude-async

A fire-and-poll MCP server that lets Claude Code run long background jobs without hitting the Claude app's tool-call timeout.

Requirements: Node.js 18+ (20+ recommended) and the claude CLI installed and authenticated. License: MIT

The problem

The Claude desktop app caps how long any single MCP tool call can run — roughly 60s per call, with a ~4–5 minute transport ceiling. A long Claude Code task (a big refactor, a multi-step build) outlives that window, the call drops, and you lose the in-flight work and start over.

Related MCP server: agent-bridge-mcp

The fix

claude-async spawns Claude Code as a detached background process and hands back a jobId in milliseconds. You poll for results whenever you like.

  • No single tool call lives long enough to time out.

  • Jobs are detached, so they survive a bridge restart — reconnect with the same jobId.

  • Output and exit status are written to disk per job, so nothing is lost.

Three tools: claude_start, claude_check, claude_jobs.

Set it up with Claude

Paste this prompt to Claude Code, or to Claude in the desktop app with this repo open. It stands the server up end to end and verifies it:

You're installing the `claude-async` MCP server from this repository. Work through
these steps in order and report the result of each. If any step fails, stop and show
me the exact error — do not continue.

1. Confirm prerequisites: `node -v` (must be 18+) and `claude --version` (the Claude
   CLI must be installed and authenticated).
2. From the repo root, run `npm install`.
3. Verify the fire-and-poll plumbing without needing a live model:
   `node claude-async-server.mjs --selftest`. It must report the detach → poll → exit
   cycle passing.
4. Register the server with Claude Desktop by running `node register-desktop.mjs`.
   (On Windows Store / MSIX installs this writes to the virtualized config path that
   the in-app "Edit Config" button does NOT open — that mismatch is a known
   silent-failure trap.) If you are not on Windows, add the config block from the
   "Manual setup" section of the README instead.
5. Tell me to fully quit and relaunch Claude Desktop, then confirm `claude-async`
   appears with status `running` under Settings → Connectors.
6. Smoke-test the round trip: call `claude_start` with the prompt "print hello world",
   take the returned `jobId`, and poll `claude_check` until `status` is `completed`
   and `exitCode` is 0. Show me the output.

Manual setup

If you'd rather not use the prompt above, or you're not on Windows:

  1. Install dependencies: npm install

  2. Verify the plumbing: node claude-async-server.mjs --selftest

  3. Register the server by adding it to your Claude Desktop config file:

    • Windows (Store / MSIX install): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json (The in-app "Edit Config" button opens %APPDATA%\Claude\ instead, which the Store build does not read. Edit the path above, or just run node register-desktop.mjs.)

    • Windows (standard install): %APPDATA%\Claude\claude_desktop_config.json

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    Add:

   {
     "mcpServers": {
       "claude-async": {
         "command": "node",
         "args": ["/absolute/path/to/claude-async/claude-async-server.mjs"]
       }
     }
   }

  1. Fully quit and relaunch Claude Desktop — closing the window is not enough. The server should then show as running.

Tools

Tool

Input

Returns

claude_start

prompt (required), workFolder?, jobId?, model?

jobId immediately; the job runs detached

claude_check

jobId (required), tailBytes?

status, exitCode, and a tail of stdout/stderr

claude_jobs

—

every known job with its current status

status is one of running | completed | failed | orphaned | unknown. completed is reported only when the job exited with code 0; a non-zero exit is failed.

Field names are camelCase throughout — it's jobId, not job_id.

Configuration

Optional environment variables:

Variable

Default

Purpose

CLAUDE_CLI_PATH

claude (on PATH)

Path to the claude binary

CLAUDE_ASYNC_JOB_DIR

~/.claude-async-jobs

Where per-job logs and exit codes are stored

CLAUDE_ASYNC_DEFAULT_CWD

$HOME

Default working directory for jobs

CLAUDE_ASYNC_DEFAULT_MODEL

claude-sonnet-5

Model used when claude_start's model param is omitted

CLAUDE_ASYNC_DEFAULT_EFFORT

medium

Reasoning effort used when claude_start's effort param is omitted

How it works

claude_start writes a small job record and spawns a detached worker (job-runner.mjs) that runs the claude CLI, streaming stdout/stderr to that job's log files and recording the exit code when it finishes. The parent returns the jobId immediately and the worker is unref'd, so it keeps running even if the MCP bridge is recycled. claude_check simply reads that job's status and log tail from disk — also instant. Because state lives on disk rather than in the live connection, a dropped or restarted bridge never costs you a running job.

On Windows, "detached" alone isn't enough for that guarantee. detached: true only puts the worker in a new process group — it does not remove it from whatever Windows Job Object the bridge itself is running in, and Claude Desktop runs MCP servers in a job with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE set (confirmed via IsProcessInJob + QueryInformationJobObject during the 2026-09-09 investigation on fix/win32-detach), so a naively-detached worker can die when the bridge does. An initial fix shelled out to win32-breakaway.ps1 (CreateProcessW with CREATE_BREAKAWAY_FROM_JOB), but runners still self-reported job membership afterward and were still observed being hard-killed. The launch path now defaults instead to a small Windows Task Scheduler-based launcher (job-launcher.mjs, registered as the ClaudeAsyncRunner task by job-core.mjs's ensureLauncherTask()) that gives the worker an ancestor — the Task Scheduler service — that was never inside Claude Desktop's process tree or job to begin with; win32-breakaway.ps1 is kept as an automatic fallback if the task can't be registered or triggered. See RUNBOOK.md's "Task Scheduler launcher" section for the full design and its verification, and test/survival.mjs for the tests (three independent kill mechanisms plus a launcher claim-race test).

Gotchas

  • Server shows running but tools don't respond: fully quit and relaunch the app; closing the window doesn't reload MCP servers.

  • Windows Store install, config edits ignored: you're editing the wrong file — see the MSIX path under Manual setup, or run register-desktop.mjs.

  • Very large claude_start prompts fail on Windows (ENAMETOOLONG): the prompt is passed as a CLI argument, so keep it modest and have the job read large inputs from a file instead.

Known issues

  • claude_check trusts the stored job record. If the bridge restarts between job completion and record close (e.g. a Claude Desktop swap), the record shows running forever while the detached job has finished and its work landed. Observed 2026-07-04 (job kanbantt-remember-token-optin: commit pushed at 01:52Z, record never closed). Fix direction: claude_check should re-stat the pid and reap exit state from the job directory rather than trusting the record.

License

MIT — see LICENSE.

Available Tools

3 tools
claude_checkA

Check a background job's status and recent output. Returns status (running | completed | failed | orphaned), exit code, and a tail of stdout/stderr.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYes
tailBytesNoBytes of stdout/stderr to return (default 8000).

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the return values but does not explicitly state that the tool is non-destructive (read-only) or mention any prerequisites, side effects, or rate limits. The 'Check' verb implies read-only, but this is not confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and contains no redundant or extraneous information. Every word contributes to clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters and no output schema, the description adequately conveys the action, return values, and the optional tailBytes parameter. It could be slightly more complete by mentioning the default tail size or that it returns only the last portion of output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% with only tailBytes having a description. The description adds context for jobId (identifies the job) and aligns with tailBytes. However, the description does not elaborate on the format or constraints of jobId beyond the schema's 'string' type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks a background job's status and recent output, specifying the returned fields (status, exit code, tail of stdout/stderr). It distinguishes from siblings by focusing on checking a specific job rather than listing or starting jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking a known job, but does not provide explicit guidance on when to use this tool versus claude_jobs (e.g., to list all jobs) or claude_start (to start a new job). No when-not-to-use or alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

claude_jobsB

List all known background jobs with their current status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description carries the full burden. It describes a read-only operation listing jobs with status, which is straightforward, but lacks details on permissions, limitations, or output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence that immediately conveys the tool's purpose. Every word contributes, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is adequate but minimal. It could hint at what 'current status' includes or list typical status values to improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema coverage is 100% trivially. Per guidelines, no parameters yields a baseline of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'list' and specifies the resource 'background jobs' with status. It clearly states what the tool does but does not differentiate from siblings claude_check and claude_start.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description only states the listing action without context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

claude_startA

Start a Claude Code task as a detached background job and return a jobId immediately. Use for any work that might run longer than ~30s. Poll with claude_check.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdNoCustom job id; otherwise one is generated.
modelNoOptional --model override, e.g. claude-opus-4-8 / claude-sonnet-4-6.
effortNoReasoning effort; default xhigh. "max" = highest reasoning; "ultracode" = xhigh plus standing dynamic-workflow orchestration (parallel subagents).
promptYesThe task for Claude Code. Include CWD context if it does file/git work.
workFolderNoDirectory to run in (default: $HOME or CLAUDE_ASYNC_DEFAULT_CWD).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It discloses that the task runs detached and returns a jobId, but does not detail error handling, side effects, or behavior on duplicate jobIds. Acceptable but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, front-loaded with purpose and usage. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description could elaborate on the return structure (e.g., jobId format). It covers the main points for a start tool, but the mention of polling and siblings could be more integrated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the parameter descriptions already provide. It mentions the prompt and workFolder in passing but without extra detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'start[s] a Claude Code task as a detached background job' and mentions it returns a jobId immediately. It distinguishes from siblings by referencing polling with claude_check and implicitly contrasting with claude_jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use this tool for work that might run longer than ~30s and directs polling with claude_check. While it doesn't enumerate when not to use it, the guidance is clear enough for typical use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedclaude_check
    • First observedclaude_jobs
    • First observedclaude_start
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a distinct purpose: starting a job, checking a specific job, and listing all jobs. No overlap in functionality.

Naming Consistency4/5

All tools share the 'claude_' prefix, but the second part mixes verbs (check, start) and a noun (jobs). Consistent prefix but slightly inconsistent in part-of-speech.

Tool Count5/5

Three tools is well-scoped for managing async background jobs, covering the essential operations without bloat.

Completeness4/5

Covers starting, checking, and listing jobs. Missing a cancel/abort tool, but the core workflow is functional.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers