agent-graph-mcp

MCP server for graph-orchestrated LLM workflows — 25 typed tools, daemon/proxy architecture, checkpoint/resume, human-in-the-loop approvals, and HMAC-authenticated execution receipts.

What it gives you

• 25 typed MCP tools — graph lifecycle, execution (sync + async), state inspection, checkpoint/resume, HITL approvals, source witnesses, templates, policy validation
• Daemon + proxy architecture — single-process daemon with file lock ownership, crash recovery, and startup mode enforcement; stateless proxy that bridges stdin/stdout to Unix socket
• Durable persistence — SQLite-backed with atomic checkpoint transactions, no partial rows after crash
• Deterministic local checkpoint/resume — HMAC-SHA256 authenticated checkpoints for linear chains of deterministic passthrough and state_transform nodes
• Built-in templates — council_deliberation (3-analyst parallel), parallel_council (debate), plan_critique_refine, analysis_pipeline, classifier_router
• Evidence witnessing — caller-supplied source capture with HMAC-authenticated receipts; locators never fetched, authority never asserted
• Crash recovery — interrupted runs report interrupted after restart; no fake running or completed state

Architecture

Hermes ──→ agent-graph-mcp (proxy) ──Unix socket──→ agent-graph-mcpd (daemon) ──→ SQLite
              stdin/stdout                framed             Tokio async I/O

Quick start

1. Build and install

cargo build --release -p agent-graph-mcp
cp target/release/agent-graph-mcp ~/.cargo/bin/
cp target/release/agent-graph-mcpd ~/.cargo/bin/

2. Start the daemon

mkdir -p ~/.local/share/agent-graph
openssl rand -hex 32 > ~/.local/share/agent-graph/integrity.key
agent-graph-mcpd --data-dir ~/.local/share/agent-graph --socket /tmp/agent-graph.sock &

3. Configure Hermes

mcp_servers:
  agent_graph:
    command: ~/.cargo/bin/agent-graph-mcp
    args:
      - --base-url
      - http://127.0.0.1:11434
      - --model
      - glm-5.2:cloud
      - --data-dir
      - ~/.agent-graph
    enabled: true

4. Verify

# Smoke test — verify no tracing pollution on stdout
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' | timeout 5 agent-graph-mcp --base-url http://127.0.0.1:11434 --model glm-5.2:cloud 2>/dev/null | grep -c '"jsonrpc"'
# Expected: 2 (initialize + tools/list response)

Tools reference

Graph lifecycle (4 tools)

Execution (5 tools)

State & checkpointing (4 tools)

Approval & evidence (5 tools)

Templates & policy (4 tools)

Status & receipts (3 tools)

Graph spec format (v2)

{
  "spec_version": "2",
  "name": "my-workflow",
  "entry": "first_node",
  "max_iterations": 32,
  "max_parallelism": 4,
  "nodes": [
    {"id": "first_node", "type": "llm", "prompt": "Process: {input}", "config": {"output_key": "result"}},
    {"id": "router", "type": "router", "config": {
      "rules": [{"path": "result", "op": "contains", "value": "deep", "targets": ["deep_research"]}],
      "default": ["summarize"]
    }},
    {"id": "deep_research", "type": "llm", "prompt": "Deep dive: {input}"},
    {"id": "summarize", "type": "llm", "prompt": "Summarize: {input}"}
  ],
  "edges": [
    {"from": "first_node", "to": "router"},
    {"from": "deep_research", "to": "END"},
    {"from": "summarize", "to": "END"}
  ],
  "reducers": {"results": "append"}
}

Node types

Council pattern example

For a 3-analyst council, use the council_deliberation template or build manually:

{
  "name": "my-council",
  "entry": "coordinator",
  "max_parallelism": 3,
  "nodes": [
    {"id": "coordinator", "type": "llm", "prompt": "Break into 3 workstreams: {input}", "json_mode": true, "config": {"output_key": "workstreams"}},
    {"id": "fanout", "type": "passthrough"},
    {"id": "analyst_0", "type": "llm", "prompt": "Research A: {input}", "config": {"output_key": "r0"}},
    {"id": "analyst_1", "type": "llm", "prompt": "Research B: {input}", "config": {"output_key": "r1"}},
    {"id": "analyst_2", "type": "llm", "prompt": "Research C: {input}", "config": {"output_key": "r2"}},
    {"id": "join", "type": "join", "config": {"inputs": ["r0","r1","r2"], "output": "findings", "mode": "collect_array"}},
    {"id": "synthesize", "type": "llm", "prompt": "Synthesize: {input}", "config": {"input_key": "findings", "output_key": "report"}}
  ],
  "edges": [
    {"from": "coordinator", "to": "fanout"},
    {"from": "fanout", "to": "analyst_0"}, {"from": "fanout", "to": "analyst_1"}, {"from": "fanout", "to": "analyst_2"},
    {"from": "analyst_0", "to": "join"}, {"from": "analyst_1", "to": "join"}, {"from": "analyst_2", "to": "join"},
    {"from": "join", "to": "synthesize"}, {"from": "synthesize", "to": "END"}
  ]
}

Daemon controls

agent-graph-mcpd --data-dir PATH --socket PATH

Environment variables:

Safety guarantees:

• Startup mode (keyed vs keyless) is durable across restarts; flipping modes is rejected
• Concurrent daemon instances on the same data directory are rejected via file lock
• Legacy schema variants (missing executions table or owner_instance_id column) are safely handled
• Socket permissions are 0600 (owner-only)
• Integrity-sensitive operations fail closed with INTEGRITY_KEY_REQUIRED when no key is configured

Capability boundary

• Runs are process-local and reported as volatile while active. With --data-dir, terminal projections and explicitly requested deterministic pre-execution checkpoints are persisted to SQLite; uncheckpointed active rows become interrupted_non_resumable after restart
• Cancellation is observed while an LLM future is in flight by dropping the local provider future (best effort). The underlying provider request may still be in flight
• Checkpoint/resume is deterministic local resume only — supports linear chains of passthrough and state_transform nodes with SQLite-bound state. LLM, router, join, parallel, loop, subgraph, and external tool nodes are excluded from resume
• Witness capture stores caller-supplied content only; locators are never fetched, and source authority is never independently verified
• Receipts use HMAC-SHA256 authentication. They do not prove an external model call occurred and are not complete replay
• Durable approval is supported only as a SQLite-backed decision over an already-created deterministic-local checkpoint; it cannot execute arbitrary Hermes tools, shell, filesystem, or provider actions

Built-in templates

Audit closure

All 28 hostile-audit findings (AG-001 through AG-028) are closed.

Verification

# Build
cargo build --release -p agent-graph-mcp

# Full test suite
cargo test -p agent-graph-mcp --lib --test daemon_recovery --test mcp_integration

# Strict clippy
cargo clippy -p agent-graph-mcp -- -D warnings

# Format
cargo fmt --check

# Publish dry-run
cargo publish -p agent-graph-mcp --dry-run

Claim boundaries

• This MCP server exposes the agent-graph runtime over the MCP protocol. It does not include LLM provider clients, prompt templating, or response parsing — those belong in llm-pipeline or the application layer
• Receipts prove structural execution — they carry cryptographic digests of the local execution trace only. They do not prove external model calls occurred or what any provider's internal state was
• Resume is deterministic local resume — it does not support resuming across LLM calls, network I/O, or external tool invocations
• Checkpoint integrity requires AGENT_GRAPH_INTEGRITY_KEY_PATH to be configured. Without it, checkpoint/resume, durable approval, terminal receipt, and source-witness operations fail closed
• Cancellation is best-effort provider future drop — the underlying model request may still complete

Ecosystem

Roadmap

• Generic replay for non-deterministic node types
• Subgraph composition with isolated state
• Dynamic parallel branch count from input data (map_reduce)
• Operator authority subsystem for authenticated HITL
• External tool integration (shell, filesystem, HTTP)
• WebAssembly target for the proxy

License

MIT — see LICENSE-MIT for details.

Built by RecursiveIntell — an applied R&D studio building local-first AI infrastructure.