MCP Server

The MCP server is the integration surface for cloud chat interfaces — ChatGPT, Claude.ai, Gemini web, Copilot Chat — that run in a browser or cloud sandbox with no local filesystem access.

If you have a shell, use the CLI binary instead. Claude Code, Codex CLI, and Gemini CLI all have shell tools. The arcflow binary exits in under 10ms, needs no configuration, and is fully composable with grep, jq, and git. MCP adds a protocol layer that those agents don't need.

MCP is correct when there is no shell. That is its exact scope.

Setup#

npx arcflow-mcp                              # In-memory (ephemeral)
npx arcflow-mcp --data-dir ./my-graph        # Persistent graph

Claude Desktop / Claude.ai#

{
  "mcpServers": {
    "arcflow": {
      "command": "npx",
      "args": ["arcflow-mcp"]
    }
  }
}

With persistent data#

{
  "mcpServers": {
    "arcflow": {
      "command": "npx",
      "args": ["arcflow-mcp", "--data-dir", "./my-graph"]
    }
  }
}

Tools#

read_query rejects all mutations — CREATE, SET, DELETE, MERGE, REMOVE are refused at the tool level. Use write_query for explicit write operations.

Tool details#

read_query and write_query#

read_query("MATCH (e:Entity) WHERE e._confidence > 0.85 RETURN e.id, e.x, e.y")
write_query("MATCH (e:Entity {id: $id}) SET e._confidence = $conf", {id: "unit-01", conf: 0.97})

ingest_nodes#

Push structured node/edge deltas. Content-hash dedup means calling the same delta twice is safe — already-ingested nodes are silently skipped.

{
  "added_nodes": [
    {
      "label": "Entity",
      "id": "unit-01",
      "content_hash": "abc123",
      "properties": { "x": 12.4, "y": 8.7, "_observation_class": "observed", "_confidence": 0.94 }
    }
  ],
  "removed_node_ids": [],
  "updated_nodes": [],
  "added_edges": [
    { "kind": "DETECTS", "from_id": "unit-01", "to_id": "contact-x" }
  ],
  "removed_edge_ids": []
}

Returns { nodes_added, nodes_removed, nodes_updated, edges_added, edges_removed, wal_bytes_written }.

create_live_view and live_view_status#

Register a view once, poll for changes:

create_live_view("high_risk", "MATCH (e:Entity) WHERE e._confidence < 0.4 RETURN e.id, e._confidence ORDER BY e._confidence ASC")
live_view_status("high_risk")
// → { frontier: 47, row_count: 3, query_text: "..." }

The frontier is a monotonically increasing mutation sequence number. If it has not changed since the last poll, the result set has not changed.

graph_rag#

Ask a natural language question answered from the world model with confidence filtering:

graph_rag("Which entities have been observed with confidence above 0.9 in the last 5 minutes?")

Snapshot envelope#

read_query and graph_rag envelopes carry a snapshot_id field — the URI of the snapshot the call observed:

{
  "snapshot_id": "arcflow://snapshot/9c3b8a1f7d2e…",
  "rows": [ ... ]
}

Both tools also accept an optional snapshot_uri input. When provided, the call is pinned to that historical snapshot and the response echoes it back. This lets a chat agent re-run a previous answer against its original world state, or pin a sequence of related questions to one consistent view.

The HTTP server exposes the same provenance via the X-Arcflow-Snapshot-Id and X-Arcflow-Manifest-Pin response headers, and accepts pinning via the ?at= query string. See Snapshot-Pinned Reads for the full surface.

Latency#

MCP operates over stdio JSON-RPC. Each tool call carries process-boundary, serialization, and JSON-RPC round-trip overhead. This is acceptable for cloud chat interfaces where the user is already waiting for a response. It is not acceptable for application code or shell agent loops.

See Also#

• CLI — the arcflow binary for shell-capable agents and developers
• Language Bindings — napi-rs (Node.js), Python, Rust, C, C++
• Agent-Native — filesystem workspace, batch execution, watch mode
• Snapshot-Pinned Reads — snapshot_id envelope and provenanced answers
• Skills — teach the world model a relationship rule in plain language; compiled once, executed at graph speed forever