This schema is the legacy 1.x surface: three one-shot, stateless Claude Code prompt tools (the README describes 2.0, which replaces them with an async task-runner API).
Run a single headless prompt against the Claude Code CLI and return the model's text response (claude_prompt), with optional model and system_prompt.
Prompt with context: same, plus free-form context text and/or file contents prepended as labeled blocks, with paths resolved relative to the server's cwd (claude_prompt_with_context).
Get structured output: run a one-shot prompt and return parsed JSON, optionally guided and lightly validated by a supplied JSON Schema (claude_prompt_structured).
Stateless only: no session persistence, resume, or state; everything runs in the server process's current working directory.
Not available here (README 2.0 instead offers): start_task, get_task, wait_task, get_events, send_message, get_diff, cancel_task, close_task, list_tasks, ask — i.e. worktree-isolated, persistent, parallel/queued tasks, steering, diffs, PRs, profiles, repo_url cloning, and HTTP mode.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claudecode-mcp claude_prompt_structured write a Python function to calculate factorial with schema validation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that runs Claude Code as an async task runner. Any MCP client can hand coding work or a review to Claude Code, track progress, steer it, and collect the result.
Each task runs in its own git worktree and branch (or in place).
Tasks are persistent sessions: they survive an MCP server restart and can
be resumed later or taken over by hand with claude --resume.
Several tasks run in parallel, up to a cap; the rest wait in a queue.
A blocking ask tool gives quick, read-only reviews and answers.
The design and its decisions are in docs/DESIGN-v2.md.
2.0 replaces the old 1.x one-shot claude_prompt* tools. It is installed
from source; it is not published to npm.
macOS or Linux. No Windows.
Node 22 or newer.
The claude CLI, version 2.1.287 or newer, on your PATH and logged
in (claude auth status). A Pro or Max subscription login works; so do
API keys and cloud providers. The server uses the claude login you
already have.
git for worktree tasks. gh (optional) for close_task draft PRs.
Related MCP server: claude-bridge-mcp
From source:
git clone https://github.com/trevoraspencer/claudecode-mcp.git
cd claudecode-mcp
npm ci
npm run buildRegister it with your MCP client, using the absolute path to dist/cli.js.
For Claude Code:
claude mcp add claudecode -- node /absolute/path/to/claudecode-mcp/dist/cli.jsOr in a client's JSON config:
{
"mcpServers": {
"claudecode": {
"command": "node",
"args": ["/absolute/path/to/claudecode-mcp/dist/cli.js"]
}
}
}Optional: npm link in the clone puts a claudecode-mcp command on your
PATH. After git pull, run npm ci && npm run build again.
claudecode-mcp --http serves the same tools over HTTP instead of stdio.
It listens on 127.0.0.1:8787 only, so put
tailscale serve in front of it to
reach it from other machines. Every request needs a bearer token; make one
per client device:
claudecode-mcp token add macbook # prints the token once
claudecode-mcp token list
claudecode-mcp token revoke macbook # takes effect at once(Without npm link, run node dist/cli.js token ... and
node dist/cli.js --http from the clone.)
Add the server's tailnet name to http.allowed_hosts (see Configuration).
Full VM setup and client registration are being written up as part of the
network-mode plan (docs/DESIGN-v2.md section 12).
Tool | What it does |
| Start Claude Code on a task in |
| Status, last result, usage, rate-limit summary, recent steps, queue position, and a take-over command. |
| Wait (up to 50 s per call) until the current turn ends. Call again to keep waiting. |
| Page through the compact transcript with a byte cursor. |
| Message a task. During a turn it joins that turn; |
| Commits, diff stat, new files, and the diff (capped at 200 KiB) since the task's base commit. |
| Stop the task. Its session can be resumed later. |
| Finish a task: |
| Task summaries, newest first, filtered by |
| Blocking question or review (up to 600 s). Read-only by default (plan mode, file-writing tools blocked). Without |
A typical flow: start_task → wait_task (loop) → get_diff →
send_message to steer → close_task with push_pr.
queued → starting → running ⇄ idle → closing → closed, plus
stalled (no events for stall_minutes, still alive), interrupted
(runner gone, e.g. after a reboot; a message resumes it), failed,
timed_out, cancelled, and rate_limited.
get_task returns a ready command, for example:
cd '/repo/.claude/worktrees/t1a2b3c4d5e' && claude --resume 6f1c…Cancel the task first if its runner is still active, so two processes never drive one session.
A server can also take a git URL instead of a local path, so callers on other machines can hand it work on repos it does not have yet. Turn it on with an allowlist in the config:
{
"workspaces_dir": "~/claudecode-workspaces",
"repo_urls": ["https://github.com/your-name/*", "git@github.com:your-name/*"]
}start_task and ask then accept repo_url (exactly one of repo or
repo_url). The server keeps one clone per repo at
<workspaces_dir>/<scheme>_<host>/<owner>/<repo>.git and fetches it before
each task.
base_ref defaults to the remote's default branch; a branch name means the
remote branch. repo_url tasks always get a worktree. Accepted URL forms:
https://host/owner/repo, ssh://user@host/owner/repo, and
user@host:owner/repo; * in a pattern matches within one path segment.
Results come back through get_diff and close_task with push_pr,
which opens the draft PR against the branch the task started from. When the
server has GH_TOKEN in its environment, it uses that token for the push
and the PR; tasks never get it, so Claude itself cannot push.
claudecode-mcp prune-workspaces [--dry-run] [--force] removes clones that
no open task uses. It only touches clones it made, and keeps a clone with
unpushed local commits, a stash, or loose files unless --force.
Optional file: ~/.config/claudecode-mcp/config.json (or
$XDG_CONFIG_HOME/claudecode-mcp/config.json, or the path in
CLAUDECODE_MCP_CONFIG). Without it, the defaults below apply. The file is
strict: unknown keys or bad values stop the server at startup with a clear
error.
{
"allowed_roots": ["~/code"],
"max_concurrent": 3,
"max_minutes": 120,
"stall_minutes": 10,
"idle_minutes": 15,
"max_events_mb": 100,
"default_profile": "worker",
"profiles": {
"worker": {
"permission_mode": "auto",
"setting_sources": ["project", "local"],
"mcp_servers": {},
"personal_skills": ["commit-style"]
},
"reviewer-clean": {
"permission_mode": "auto",
"setting_sources": ["project"],
"skills": false
}
}
}Key | Default | Meaning |
| your home folder | Repos must be inside one of these (checked by real path). |
| 3 | Turns running at once; more tasks wait as |
| 120 | Cap per turn. Idle time does not count. |
| 10 | Flag a turn as |
| 15 | Keep an idle |
| 100 | Cap on a task's transcript; reaching it stops the task. |
|
| HTTP mode listen address. Loopback only ( |
| 8787 | HTTP mode port. |
|
| MCP endpoint path. |
|
| Extra |
|
| Browser origins to accept. Requests with any other |
|
| Per-device token hashes (mode 0600). |
|
| Managed clones for |
|
| Allowlist of URL patterns for |
A profile decides how the child Claude Code is set up, separate from your
personal setup. The default worker profile uses auto permission mode, no
MCP servers, and the target repo's own settings, hooks, skills, and
CLAUDE.md.
Field | Effect |
|
|
| Which settings load: |
| A settings file path or an inline settings object. |
| The exact MCP servers for the child. This server is never allowed. |
| Use your own MCP servers too. |
| Block tools, or allow only these built-in tools. |
| Load these plugin folders. |
|
|
| Chosen hooks from your |
| Chosen skills from |
| A fully separate Claude home (needs its own login). |
| Defaults for the child. |
Run claudecode-mcp list-personal-config to see your hooks (with indexes)
and skills.
Permissions: auto mode lets a safety check decide each action and
blocks high-risk ones (see claude auto-mode defaults). Nothing ever waits
for a person: anything that would prompt is denied and reported in
permission_denials.
Repo URLs: only URLs matching repo_urls are cloned; other schemes
(ext::, http://, git://, file://), credentials in URLs, and
option-like values are refused, and git may only use https and ssh.
Isolation: worktree tasks never touch your main checkout. Worktrees are
excluded from your git status.
No recursion: the child gets CLAUDECODE_MCP_DEPTH; a nested server
refuses to start tasks, and profiles cannot reset that marker.
Environment: the child gets an explicit allowlist of variables, never your whole environment. Host-session variables are never passed.
HTTP mode: loopback only, a per-device bearer token on every request (checked in constant time; only hashes are stored), Host and Origin checks, and an 8 MiB body cap. Anyone with a token can run Claude Code on that machine, so give each device its own token and revoke lost ones.
Data: task state lives in ~/.local/state/claudecode-mcp (mode 0700).
Errors sent to clients are redacted.
~/.local/state/claudecode-mcp/ ($XDG_STATE_HOME, or CLAUDECODE_MCP_STATE_DIR)
tasks/<task-id>/task.json status, session, workspace, result, usage
tasks/<task-id>/events.jsonl full stream-json transcript
tasks/<task-id>/runner.log the runner's own log
sessions/<session-id>.lock one process per sessionEach task has a detached runner process, so tasks keep running when the MCP server restarts. A restarted server finds them on disk.
Variable | Use |
| Config file path. |
| State folder (keep it short: socket paths are limited to 103 bytes). |
| Path to the |
| Path to the |
| Comma-separated extra variables to pass to the child. |
|
|
| Queue dispatcher interval (default 2000). |
|
|
| HTTP mode: how long SIGTERM waits for in-flight requests (default 10000). |
| Structured debug logs on stderr. |
claude CLI ... is too old: update Claude Code to 2.1.287 or newer.
claude started in permission mode "default", not "auto": auto mode
needs sonnet or opus. Pick one of those models, or a
bypassPermissions profile.
repo is outside allowed_roots: add the folder to allowed_roots.
not a git repository: pass isolation: "in_place".
A task shows interrupted: its runner stopped (reboot, crash). Send it
a message to resume.
Runner problems: see tasks/<id>/runner.log in the state folder.
npm install
npm run format:check && npx tsc --noEmit && npm test
npm run test:live # tiny real prompts; needs a logged-in claudeOffline tests use a fake claude that emits stream-json. See
AGENTS.md for invariants and conventions, and
CONTRIBUTING.md for pull requests.
MIT
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode (no session persistence, no resume). Returns the model's text response. Uses the server process's current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: stateless operation, no session persistence, no resume capability, and that it uses the server's current working directory. However, it doesn't mention rate limits, authentication requirements, error handling, or response format details that would be helpful for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality and key behavioral constraints. The second sentence provides important operational context about the working directory. There's zero wasted language or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides adequate but incomplete context. It covers the operational mode and working directory context well, but doesn't address what the return value looks like (only says 'Returns the model's text response' without format details), error conditions, or performance characteristics that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all three parameters thoroughly. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it doesn't explain parameter interactions, provide examples, or clarify usage patterns. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Run a one-shot prompt'), target resource ('Claude Code CLI'), and operational mode ('headless, stateless mode with no session persistence, no resume'). It distinguishes from siblings by specifying this is a one-shot operation without persistence, unlike tools that might maintain context or structure outputs differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('headless, stateless mode with no session persistence, no resume'), which implicitly suggests alternatives when persistence or session management is needed. However, it doesn't explicitly name sibling tools or provide explicit 'when-not-to-use' guidance beyond the stateless nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode and return a structured JSON object. If schema (a JSON Schema) is provided, the tool instructs the model to conform to it and validates the parsed output against the schema (basic type/required-field checks). Returns the parsed JSON as the tool response content. Uses the server process's current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| schema | No | Optional JSON Schema describing the expected shape of the model's JSON output. Used both as an instruction to the model and for lightweight post-hoc validation. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the tool runs in 'headless, stateless mode', validates output against a schema if provided, returns parsed JSON, and uses the 'server process's current working directory'. This covers execution mode, validation behavior, and environmental context, though it lacks details on error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first. Every sentence adds value: the first defines the action and output, the second explains schema usage, and the third provides environmental context. There is no wasted text, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a 4-parameter tool with no annotations and no output schema, the description is mostly complete. It covers the tool's purpose, behavioral traits, and usage context. However, it lacks details on error cases, response format beyond 'parsed JSON', or performance considerations, leaving minor gaps for a tool with no structured safety hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, only mentioning that the schema is 'used both as an instruction to the model and for lightweight post-hoc validation'. This aligns with the baseline score of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a one-shot prompt against the Claude Code CLI in headless, stateless mode and return a structured JSON object.' It specifies the verb ('Run'), resource ('Claude Code CLI'), and distinguishes from siblings by mentioning 'structured JSON object' and schema validation, unlike the generic 'claude_prompt' and context-aware 'claude_prompt_with_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for 'one-shot prompt' execution in 'headless, stateless mode' with structured JSON output. It implies usage for schema-constrained responses but does not explicitly state when NOT to use it or name alternatives like the sibling tools, though the structured output focus differentiates it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-shot prompt against the Claude Code CLI in headless, stateless mode, with additional free-form context and/or file contents prepended to the prompt. Returns the model's text response. Uses the server process's current working directory; file paths are resolved relative to cwd.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user prompt to send to Claude Code. | |
| context | No | Optional free-form context text to prepend to the prompt. | |
| files | No | Optional list of file paths whose contents will be read and prepended to the prompt as labeled context blocks. | |
| model | No | Optional Claude model alias or full name (e.g. 'sonnet', 'opus'). | |
| system_prompt | No | Optional system prompt to use for this turn. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral traits: 'headless, stateless mode', 'Returns the model's text response', and 'Uses the server process's current working directory; file paths are resolved relative to cwd.' However, it lacks details about rate limits, authentication needs, error conditions, or response format specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the core functionality and key differentiators, the second adds important operational context about working directory and file path resolution. Every element earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and no output schema, the description provides adequate but not complete coverage. It explains the core operation and some behavioral context but lacks details about response format, error handling, or model selection implications. For a tool with this complexity and no structured safety/behavior annotations, more completeness would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds some context about how 'context' and 'files' parameters work ('prepended to the prompt'), but doesn't provide significant additional meaning beyond what's in the schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run a one-shot prompt'), the target ('Claude Code CLI'), the mode ('headless, stateless mode'), and key differentiators from siblings ('with additional free-form context and/or file contents prepended'). It distinguishes this tool from 'claude_prompt' and 'claude_prompt_structured' by emphasizing the context/file prepending capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('with additional free-form context and/or file contents prepended to the prompt'), which implicitly suggests alternatives when such context isn't needed. However, it doesn't explicitly state when NOT to use it or name specific sibling alternatives beyond the general differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0claude_promptclaude_prompt_structuredclaude_prompt_with_contextScored across 3 tools
The three tools have clearly distinct purposes: one returns plain text, one returns structured JSON, and one accepts additional context/files. However, the core functionality of running a one-shot prompt is identical across all three, which could cause minor confusion about when to use each variant.
All tool names follow a perfect 'claude_prompt_' prefix pattern with descriptive suffixes (_structured, _with_context). The naming is completely consistent and predictable, making it easy to understand the tool hierarchy at a glance.
Three tools is reasonable for a Claude Code CLI interface, covering the main variations needed (text, structured, contextual). However, this feels slightly minimal - additional tools for session management or configuration might be expected but aren't strictly necessary for the stated headless, stateless approach.
The tools cover the basic prompt execution variations well, but there are notable gaps for a complete Claude Code CLI surface. Missing operations include session management (contradicting the stateless approach), model selection, parameter tuning, streaming responses, and error handling tools that would be expected for production use.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
