Harflow MCP

HarflowMCP

HarflowMCP is a local MCP server that dispatches coding tasks to Claude Code, Codex, opencode, Vibe, Antigravity, and the Cursor Agent CLI. It provides persistent task history, bounded reads, cancellation, continuation, and reusable workflows. On measured Claude Code versions, callers can opt in to approving individual Bash, Read, Write and Edit requests one exact action at a time (see harness permissions); on macOS with codex-cli 0.163.0 the same opt-in approves individual Codex commands and, with caller_write_approvals, patches through codex app-server (see Codex caller approvals), and can grant a task a bounded list of specific Bash commands with allowed_commands instead of unrestricted access (see dispatch-time command grants).

Signing into the Cursor editor does not sign in the agent CLI. Headless Cursor dispatch needs agent login or CURSOR_API_KEY. Confirm with agent status: it has to report an access token. That check reads the CLI credential store for the current HOME, so a shell whose home directory is somewhere else still says it is not logged in after a successful agent login. Cursor refuses caller approvals and allowed_commands. Its read_only launch asks for plan mode; write_in_repo, publish, and unrestricted share one print-mode command until a measured boundary separates them. There is no live follow-up on stdin. The pinned CLI is 2026.10.22-27dcf5f on macOS arm64. See harness permissions and backend CLI facts.

MCP task status and single-task waits default to compact polling while preserving the complete final summary, approval attention and recovery diagnostics. Use detail="full" for execution metadata; include_tail=true explicitly includes the raw tail in either mode. Workflow discovery returns names, descriptions, revisions and IDs by default; get_workflow(name) reads the full graph. Prefer wait holds of 50 seconds or less on remote MCP connections. See the waiting and polling guide.

Task ids and workflow run ids may be passed as unique prefixes of at least 8 characters; replies echo the resolved id in resolved_from, and an ambiguous prefix lists its candidates. See id prefixes.

While bounded reads are still establishing caller authority, preparation responses expose only neutral status, source and reason, with empty content and unknown counts. This also applies to a cold index for a direct caller; retry until authority is established. See bounded read authority.

After a dispatch server restart, surviving execution is reported as a quiet observation change; lost or uncertain owner/capture evidence remains visible. Full diagnostics retain the original dispatcher identity. See supervision. For stable read-only parent-process observation continuity, use harflow-ctl status TASK_ID --observer-parent --json (also supported by status-batch); see public contracts.

Builders support explicitly requested conversational turns through ctl and agent MCP steering. A prose reply waits for another caller request; a valid framed proposal remains subject to draft revision checks and explicit Apply/Save. This requires the qualified original external caller or a verified native human and a supported finite harness cap. Ordinary builder messages keep their existing behavior. See builder steering. Orchestrators also support safe-boundary conversation with exact decision revisions: prose waits, and only a framed, validated configured action can resume execution. Already issued work and active sibling results remain real. See orchestrator steering.

Qualified workers support one finite response per explicit caller message, with their actual configured permissions and real tool effects. Steering does not consume or reset normal execution attempts. Epoch-scoped replay and bounded retention require an explicit protocol upgrade; old receipts may expire with visible history gaps. See worker steering and bounded history.

Root connected workers configured headless in fixed Fresh mode also support exact prestart withdrawal and a linked same-assignment retry. A spawn race stays unknown; the operation never authorizes a late signal or poststart replacement. See prestart worker replanning.

Workflow callers can see every pending child question in status and wait replies and answer them independently by decision ID through the root run. Questions and structured clarification items remain complete, and forwarded answers return a durable child acceptance receipt. Resolved attention reasons disappear when execution resumes; unreadable workflow approval metadata is reported separately from requests needing a decision. See workflow input and recovery.

Permission features use cached, binary-bound qualification: measured versions seed the cache, and unseen versions run isolated no-paid behavior probes before use. harflow-ctl qualify explicitly reruns the probes; cached discovery reports per-feature results. Add --qualification-only to permission-preview or workflow-preview NAME to discover only the features requested by that launch without provider self-tests; qualify --feature FEATURE is repeatable. Ordinary permission previews may qualify requested features. Automatic probes currently require macOS isolation. See qualification.

Current seed measurements for these two features: allowed_commands is qualified on Claude Code 2.1.310 and 2.1.312 and Vibe 3.0.3 on macOS through ACP; caller approvals are qualified on Claude Code 2.1.302 (Bash approvals) and 2.1.310/2.1.312, and on Codex through codex app-server for codex-cli 0.163.0 on macOS only (commands, and patches with caller_write_approvals), and on Vibe 3.0.3/macOS through vibe-acp (Bash and file reads; writes/edits with caller_write_approvals); other backends refuse them. Approvals are not available to native workflow children, and a request unanswered after 1800 seconds (or at the node's attempt deadline) is rejected by Harflow, never approved. After a denial there is no approve-later path: recovery is always a new resume_task or continue_task execution guided by denial_remedy (allowed_commands covers only Bash approval_required and chained-command parts; a denied Read, Write or Edit needs a resumed run so the agent can raise a fresh request; a deny_rule cannot be lifted by grants). Workflow permission-grant retry remains unavailable. On compatible engines the Mac Monitor can answer caller-owned requests; authority follows the existing inferred, cooperative same-user model and does not authenticate a human or the app. See harness permissions.

Vibe 3.0.1 and 3.0.3 headless dispatch use its Rust CLI and the ask approval profile for read_only. This is an approval policy, not a write-tool exclusion: inherited policies or custom profiles can pre-approve writes. The retained VIBE_CLI=python selector is ignored by Vibe 3; interactive takeover inherits the user's environment.

Vibe permission results retain structured tool refusals and the scopes requested by approval callbacks. Known refusal shapes distinguish approval requirements, policy denials and denylist rules; unknown reasons remain unclassified. Vibe 3.0.3/macOS uses a qualified ACP transport for caller approvals, allowed_commands and explicit configured-model selection. Requests and responses are bound to the exact tool input; grants never replace the native allowlist or override native deny policies. Ordinary launches without these options retain the established headless transport. See Vibe permission denials.

Vibe provider HTTP 402 failures retain a safe explanation even without final agent prose. A measured usage-limit response is reported as a usage limit; an unknown payment response stays a provider error and asks you to check billing and usage. Neither automatically retries or switches providers.

publish authorizes publication attempts; its enforcement depends on the backend:

Claude's built-in list excludes merge, repository deletion, releases and raw gh api calls. Its prefix matcher cannot safely distinguish read API calls from writes; use gh pr view --json or gh repo view --json for supported reads. These are Harflow-supplied command grants, not an OS Git sandbox; inherited settings and hooks can still allow or deny commands. Permission previews expose the actual mechanism and caveats. See publication permissions.

Version 0.0.10 is a pre-release candidate. Harflow, the companion macOS application, is maintained separately and prepares its own exact paired engine runtime. Its managed runtime and MCP registrations work independently of the app process; see the managed runtime guide.

Task phase slots can serialize heavy commands while code-writing tasks overlap. Explicit human enable, durable FIFO leases and optional conservative host cleanup are documented in phase slots; Monitor queue UI remains outstanding. Phase operations distinguish a disabled layout with the stable error code phase_slots_not_enabled; see the phase slot contract.

Detached task owners preserve output capture and live input across MCP server restarts. Tasks can take turns on a named, exclusive resource (a simulator, a device, a database) with resources; a waiting task is acknowledged at once and reports waiting_for_resources until it spawns. A task can also run in its own linked Git worktree with worktree, leaving your checkout untouched. Workflows can declare run and node resource scopes and share one root-run worktree across nodes and linked child runs. See resources and worktrees. Final review summaries and workflow plans receive task-identifiable files discoverable through task artifacts, including read-only runs. Child workflows receive pinned parent specifications throughout their nodes. Every task also gets scratch folders shared across its resume chain and its group (HARFLOW_CHAIN_SCRATCH, HARFLOW_GROUP_SCRATCH), so outputs su