How MC-AI Works

MC-AI is a workflow engine built around four concepts: Graphs, Nodes, State, and Reducers. Understanding how these fit together is the key to building effective workflows.

The four pillars

1. Graph

A Graph is the definition of a workflow — a set of nodes connected by edges. Graphs can be cyclic: nodes can loop back to previous nodes, enabling self-correction, iterative refinement, and dynamic routing.

research → writer → reviewer → (done | back to writer)

Graphs are defined in TypeScript (or generated by the Architect) and can be versioned, composed into subgraphs, and updated without redeploying.

2. Nodes

A Node is a unit of work. There are 10 node types:

Type	What it does
agent	Runs an LLM with optional tools. The most common node type.
supervisor	An LLM-powered router that dynamically delegates to managed nodes.
evolution	Runs N candidate agents in parallel, scores them, and breeds the next generation.
tool	Executes a specific MCP tool directly without an LLM.
router	Conditional routing based on state expressions.
synthesizer	Merges parallel outputs into a single coherent result.
voting	Multiple agents vote to reach consensus.
map	Fan-out to parallel workers (map-reduce pattern).
approval	Pauses workflow for human review before continuing.
subgraph	Delegates to a nested graph with its own isolated state.

3. State (the Blackboard)

Instead of passing output directly between nodes, all nodes read from and write to a shared blackboard called WorkflowState. This is a typed JSON object that can be persisted after every node completes.

{
  goal: "Write a blog post about AI Agents",
  memory: {
    topic: "Future of Autonomous Agents",
    notes: "...",     // written by researcher
    draft: "...",     // written by writer
  },
  status: "running",
  iteration_count: 4,
}

Nodes read only the keys they’re permitted to access (read_keys) and write only to the keys they’re allowed to modify (write_keys). This enforces state slicing — no node sees more than it needs to.

4. Reducers

Agents never mutate state directly. Instead, they emit actions (structured data), and a pure reducer function merges the action into the existing state:

(CurrentState, Action) → NewState

This design has important benefits:

• No race conditions — parallel nodes can’t corrupt shared state
• Full auditability — every state change is tied to an explicit action
• Crash recovery — state is a pure function of all actions applied so far

Execution flow

When a workflow runs:

1. The GraphRunner loads the graph definition and the initial state
2. It evaluates the start node
3. For each node, the runner: executes the node, receives an action, applies the reducer, persists the new state, evaluates the next edge condition
4. If an edge condition returns a target node, execution continues there
5. If the workflow reaches an end_node or the supervisor routes to __done__, the run completes

Persistence and resumability

State can be persisted (in-memory by default, Postgres via @mcai/orchestrator-postgres) after every node execution. This enables:

• Time-travel debugging — inspect state at any point in the workflow
• Resumability — restart from the last checkpoint after a crash
• Human-in-the-Loop — pause mid-workflow, wait for human input, resume exactly where it left off
• State versioning — retrieve any previous version of the state for a run

Next steps

• Graphs & Nodes — the full node type reference
• Workflow State — what’s in the blackboard and how to use it
• Agents — how agents are defined and executed
• Reducers — how state changes work