Skip to main content
Glama
wyrd-company

async-claude-agentsdk-mcp

by wyrd-company
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

async-claude-agentsdk-mcp

An MCP server that lets coding agents run Claude Agent SDK sessions as asynchronous sub-agents.

claude and claude-continue return as soon as the background turn is scheduled. They never hold an MCP request open while Claude works. claude-status is an immediate point-in-time read of the in-memory session state.

Tools

claude

Starts a new Claude session and immediately returns a wrapper-owned session_id.

Inputs:

  • prompt (required): the task for Claude;

  • model (optional): a Claude model override;

  • effort (optional): low, medium, high, xhigh, or max;

  • cwd (optional): the working directory for the session.

Example result:

{
  "session_id": "0bd9d545-6016-4a5e-89b7-93f85a059f38",
  "status": "running",
  "turn": 1,
  "message": "Claude is running asynchronously. The MCP call is complete."
}

claude-continue

Starts another background turn in a completed session. It keeps the wrapper session_id and resumes the underlying Claude Agent SDK session.

Inputs:

  • session_id (required): the handle returned by claude;

  • prompt (required): the next prompt.

Continuation is rejected while the preceding turn is running or if it failed without producing a resumable Claude session.

claude-status

Returns the current state without waiting for a change. The response includes:

  • lifecycle status: running, completed, or failed;

  • the underlying Claude session ID once the SDK reports it;

  • the latest status summary and todo list reported by Claude;

  • caller-relevant problems reported by Claude;

  • the latest completed result or failure;

  • originating Codex session, thread, and turn IDs when Codex supplied them in MCP _meta.

Related MCP server: claude-mcp-bridge

Claude status reporting

Every Claude run receives an in-process MCP server with two tools:

  • report_status: replaces the current todo list and optionally records the current focus;

  • report_problem: appends a risk, blocker, or failure for the caller.

The tools only update session state and send best-effort MCP logging notifications. They do not block Claude waiting for the caller. Native TodoWrite calls are also captured when present in the Agent SDK message stream.

Permissions

The default permission mode is bypassPermissions. This intentionally gives Claude unrestricted tool execution in its environment and requires the Agent SDK's allowDangerouslySkipPermissions acknowledgement.

Set ASYNC_CLAUDE_MCP_PERMISSION_MODE to change it:

export ASYNC_CLAUDE_MCP_PERMISSION_MODE=default

Accepted values are default, acceptEdits, bypassPermissions, plan, dontAsk, and auto.

Run

Run the latest published version without installing it globally:

npx --yes @wyrd-company/async-claude-agentsdk-mcp

Example Codex configuration:

[mcp_servers.async_claude]
command = "npx"
args = ["--yes", "--@wyrd-company:registry=https://registry.npmjs.org", "@wyrd-company/async-claude-agentsdk-mcp"]

The server uses stdio and writes protocol messages only to stdout. Claude Agent SDK authentication and settings are inherited from the server process environment.

The explicit scope registry in the Codex configuration ensures npmjs is used even when the local npm configuration routes @wyrd-company packages to another registry.

For a global installation instead, run npm install --global @wyrd-company/async-claude-agentsdk-mcp and use async-claude-agentsdk-mcp as the command.

Session records are in memory. They survive multiple MCP tool calls and Claude turns while the stdio server remains running, but they do not survive a server restart.

Publishing

The package is published publicly to npmjs and GitHub Packages as @wyrd-company/async-claude-agentsdk-mcp. The Publish Package GitHub Actions workflow validates the release, publishes to npmjs with provenance using the repository's NPM_TOKEN Actions secret, and then publishes to GitHub Packages using its GITHUB_TOKEN.

Run the workflow manually, or push a bare SemVer tag that exactly matches the version in package.json, for example 0.1.0. Tags prefixed with v do not trigger publishing.

The GitHub Packages release inherits the public repository's visibility and permissions. Publishing npmjs first lets a failed GitHub Packages job be retried without attempting the immutable npmjs version again.

After the first release creates the npmjs package, configure npm trusted publishing for publish-package.yml and remove NODE_AUTH_TOKEN from the npmjs job to eliminate the long-lived publishing token.

Development

npm install
npm test
npm run build
npm start

Available Tools

3 tools
claudeA

Start a Claude Agent SDK session in the background and immediately return its session handle.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for Claude.
modelNoClaude model override for this session.
effortNoReasoning effort for this session.
promptYesPrompt to send to Claude.

TDQS

A3.6/5.0
Behavior3/5

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

Describes background execution and immediate return of session handle, but with no annotations, it lacks details on critical behaviors such as session limits, concurrency, error states, or how the handle is used by sibling tools.

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?

Single sentence with front-loaded verb and clear object. No unnecessary words; every part contributes meaning. Highly efficient.

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

Completeness2/5

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

No output schema, and the description omits the return format of the session handle, usage flow with sibling tools, and any constraints. For a tool starting a background session, this leaves significant gaps for an AI agent.

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?

Input schema provides 100% coverage with descriptions for all four parameters. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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?

Description clearly states the action: start a Claude Agent SDK session in background and return session handle. It differentiates from siblings (claude-continue, claude-status) by being the initial session starter.

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?

Implied usage as the first step in a multi-tool workflow, but no explicit guidance on when to use vs alternatives (e.g., claude-continue). No exclusions or prerequisites mentioned.

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

claude-continueB

Start another background turn in a completed Claude session and immediately return.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesPrompt for the next turn in the completed session.
session_idYesSession handle returned by claude.

TDQS

B3.3/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It mentions 'background turn' and 'immediately return' hinting at async behavior, but does not disclose side effects, auth requirements, rate limits, or whether multiple calls are safe.

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?

Single sentence, no redundancy, every word earns its place. Front-loaded with core action.

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 simple tool with 2 simple parameters and no output schema, the description is minimally adequate. However, it does not clarify important details like whether the prompt is appended to history or how errors propagate.

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 description coverage is 100% and already documents both parameters. The description adds no further detail about format, constraints, or usage beyond what the schema provides, so baseline 3 is appropriate.

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 uses a specific verb 'Start another background turn' and identifies the resource 'completed Claude session'. It clearly distinguishes from siblings: 'claude' likely starts a session, 'claude-status' checks status.

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 explicit guidance on when to use this tool versus siblings. It implies usage on completed sessions but does not mention when not to use or provide context like prerequisites.

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

claude-statusA

Return an immediate snapshot of a Claude session, including current todos and reported problems.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession handle returned by claude.

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations provided, the description carries full burden. It indicates a non-destructive read operation ('immediate snapshot') and states return content, but omits details like side effects, authentication requirements, rate limits, or error handling.

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, efficient sentence of 16 words. It is front-loaded with the core idea and contains no unnecessary information or redundancy.

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?

For a simple status tool with one parameter and no output schema, the description adequately covers what the tool does and returns. However, it could be marginally improved by mentioning error conditions for invalid session IDs.

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 description coverage is 100% for the single parameter, so baseline is 3. The tool description adds no extra meaning beyond the schema's description of 'session_id' as a session handle.

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 action ('Return an immediate snapshot'), the resource ('a Claude session'), and the contents ('current todos and reported problems'). It effectively distinguishes from siblings 'claude' (start session) and 'claude-continue' (continue session) by focusing on status retrieval.

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 after session start by referencing 'Claude session' and 'session_id', but lacks explicit guidance on when to use this tool versus alternatives, such as stating 'Use after starting a session with claude' or noting prerequisites.

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 updatesv0.1.0
    • First observedclaude
    • First observedclaude-continue
    • First observedclaude-status
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.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct action on a session: starting, continuing, and checking status. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow the same hyphenated pattern with a 'claude-' prefix and action verb, ensuring predictability.

Tool Count5/5

Three tools is appropriate for managing Claude sessions—covering initialization, continuation, and status—without being too few or too many.

Completeness3/5

The set covers starting and reading status, but lacks an explicit end/stop session tool, which could hinder agent workflows requiring session cleanup.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers