MCPX

A durable control plane for long-running AI-agent work over the Model Context Protocol.

MCPX is for workflows that cannot safely assume the model will remember the previous turn, the client will display every tool result, or a long-running command will finish before the MCP server restarts.

It adds durable work packets, crash-safe/idempotent side effects, revision-bound workspace handles, verified producer/audit generations, background-job recovery and scope-aware reconciliation around ordinary MCP filesystem and execution tools.

Status: v0.1.0 is an early public release extracted from a production-used implementation. The strongest atomic file publication helper is currently macOS/Darwin-specific.

Why MCPX exists

A normal MCP tool call is easy. A multi-hour or multi-day agent workflow is harder:

• the client may hide or lose a tool result after the side effect already happened;

• retrying can duplicate an expensive or destructive operation;

• a process may outlive the model turn or the MCP server;

• multiple agents may work under parent/child project roots that map to the same physical files;

• an old unfinished workspace may coexist with newer canonical results;

• a validator must audit an exact immutable generation rather than a moving directory.

MCPX makes those execution facts durable and queryable.

Related MCP server: oflow-mcp

Core ideas

Workspaces are durable work packets

A workspace is both an isolation mechanism and a durable record that a logical piece of work is unfinished. open means unfinished; it does not mean “latest” or “authoritative.”

Exact retries are idempotent

Every side effect carries an operation_id. A new logical action gets a new id. If a response is lost, the exact same call can be retried with the same id; MCPX recovers/returns the durable action instead of replaying it blindly.

Scope is physical, not merely nominal

MCPX canonicalizes mutable filesystem paths across registered roots. A workspace rooted at /project mutating paper/x conflicts with a workspace rooted at /project/paper mutating x.

READY generations are immutable audit boundaries

Verified producers publish a READY build only after validation and complete artifact hashing. Verified consumers bind to an exact build id and re-hash the candidate before and after the audit.

Requirements

• macOS (v0.1.x atomic file transaction helper uses Darwin atomic swap primitives)

• Node.js 22+

• Python 3.10+

• Xcode Command Line Tools / swiftc

• optional: Poppler (pdfinfo, pdftotext) for PDF text extraction

• optional: Codex CLI if using MCPX_WORKSPACE_SANDBOX=codex

Install

git clone https://github.com/azazhang/mcpx.git
cd mcpx
npm ci
npm run build:filetxn

Configure a canonical root:

export MCPX_BASE_DIR="$HOME/Research"

Start MCPX:

npm start

The default endpoint is:

http://127.0.0.1:9090/mcp

MCPX does not provide authentication. Keep it loopback-only unless you deliberately place a trusted authenticated transport in front of it.

Safe command-execution default

The public build does not expose command-starting tools by default.

To enable them in a trusted local deployment:

export MCPX_ENABLE_COMMAND_EXECUTION=1
export MCPX_WORKSPACE_SANDBOX=none

none is not an OS sandbox. To use the same optional Codex sandbox integration used by the original deployment:

export MCPX_ENABLE_COMMAND_EXECUTION=1
export MCPX_WORKSPACE_SANDBOX=codex
export MCPX_CODEX_BIN="$(command -v codex)"

See SECURITY.md before enabling command execution or remote access.

Important tools

• reconcile_project_state — recover scope-relevant unfinished work plus recent integrated history.

• create_agent_workspace — create a BASE/work copy with declared mutable paths.

• integrate_agent_workspace — BASE/CURRENT/PROPOSED reconciliation into canonical state.

• remove_agent_workspace / resume_workspace — lifecycle management with preservation of divergent work.

• start_verified_workspace_producer — publish a validated READY generation.

• start_verified_workspace_consumer — audit an exact READY build and verify it stayed unchanged.

• start_command, execute_command, command_status — durable execution/job registry (opt-in for command starts).

Tested failure modes

The adversarial suite covers, among other cases:

• exact retry after project topology changed;

• overlapping parent/child project roots;

• stale workspace handles;

• simultaneous same-handle mutation races;

• integration/retirement refusal while jobs run;

• server restart and durable job recovery;

• crash after an operation is claimed but before dispatch;

• verified producer/consumer build binding;

• dirty retirement preservation;

• suspension/resume of divergent idle work;

• orphan workspace quarantine;

• maintenance racing a workspace command;

• oversized result preservation.

Run the suite with:

npm test

Documentation

• Architecture

• Operating model

• Security

• Contributing

Project history

MCPX grew out of repeated failures observed in long-running agent/research workflows: hidden tool responses, duplicate retries, stale connector schemas, phantom jobs, nested-root concurrency, abandoned workspaces and audits accidentally targeting stale generations. The public repository contains the generalized control-plane implementation and synthetic/adversarial tests, not the private projects that originally exercised it.

License

Apache License 2.0. See LICENSE.