@causari/mcp-server

Wikipedia for AI agents. A Model Context Protocol server that gives Claude Code, Cursor, Windsurf — or any MCP-compatible AI agent — structured causal knowledge: 245 events, 631 causal links with confidence scores, and 8 insight patterns across 9 verticals of technology history.

Install in 60 seconds

{
  "mcpServers": {
    "causari": { "command": "npx", "args": ["-y", "@causari/mcp-server"] }
  }
}

Add to .mcp.json (Claude Code) or ~/.cursor/mcp.json (Cursor). Restart your IDE. Done.

3 things you can do

1. "Why does Kubernetes exist?" → causal_chain("kubernetes", depth: 3) returns: Docker containers → Linux cgroups → Unix philosophy → and the pattern that open standards win infrastructure wars. Every link has evidence + confidence.

2. "My startup competes with a closed platform using an open protocol" → historical_resonance(...) matches TCP/IP vs OSI, Linux vs proprietary Unix, Web vs AOL. Returns predictive value scores and historical exemplars.

3. "High-impact computing events 1990-2010" → query_events(yearFrom: 1990, yearTo: 2010, domains: ["technology"]) returns Linux, World Wide Web, Java, Google, iPhone, Bitcoin — structured, filterable, scored by impact.

Why this exists

Wikipedia is excellent for humans, but unstructured for AI parsing. When you ask Claude "trace what led to the Transformer architecture", it stitches together prose memory — fluent but unsourced and uncalibrated.

This MCP server hands the agent a structured causal graph instead:

• Nodes: historical events with year, domain, impact score, sources
• Edges: causal links (caused / enabled / accelerated / delayed / prevented) with confidence + evidence text
• Patterns: recurring causal insights ("Information Democratization Cycle", "Substrate Substitution") that the agent can reuse for analogical reasoning

The agent reasons over real structure — and tells the user what it knows, where it's calibrated, and where it isn't.

| | Plain Claude / Wikipedia lookup | Causari MCP | |---|---|---| | Output shape | Prose paragraphs | Structured nodes + edges | | Causal claims | Stitched from memory | Edges with confidence 0–1 + evidence text | | Provenance | None inline | Source attributions per event | | Pattern matching | Ad hoc | Named insight patterns reusable across queries | | Token cost | High (verbose prose) | Low (compact JSON, no redundant fields) | | Multi-hop reasoning | Implicit, opaque | Explicit BFS over the graph |

Tools

| Tool | What it does | When to call it | |---|---|---| | query_events | Search events by time / domain / impact / free text | You need historical context for a topic, era, or domain | | causal_chain | BFS up/down the causal graph from a root event | You need to understand why something happened, or what it enabled | | historical_resonance | Find historical patterns parallel to a present-day situation | You're reasoning about a current trend and want analogies with predictive value | | org_knowledge | (Enterprise tier) Query an organization's private CKG | Working inside an enterprise namespace with private events configured | | predict_scenarios | Generate scenario branches from current conditions + historical patterns | Strategic planning, stress-testing assumptions, risk assessment |

In Claude Code these surface as mcp__causari__causal_chain (and similar), depending on the IDE's prefixing convention.

Tool reference — with examples

Every example below is a real call against the bundled graph, with the response trimmed for readability. Inputs are validated at the boundary: out-of-range numbers, unknown domains, NaN, and empty required fields are rejected with a clear message the agent can act on.

query_events

Search the graph by time window, domain, impact, or free text.

// arguments
{ "yearFrom": 1990, "yearTo": 2010, "domains": ["technology"], "minImpact": 0.85, "limit": 4 }

// response (trimmed)
{
  "events": [
    { "id": "web",   "title": "World Wide Web", "year": "1991", "impactScore": 0.92 },
    { "id": "linux", "title": "Linux Kernel",   "year": "1991", "impactScore": 0.92 },
    { "id": "aws",   "title": "AWS / Cloud Computing", "year": "2006", "impactScore": 0.88 }
  ],
  "totalMatched": 7,
  "truncated": true,
  "hint": "7 events matched but only 4 returned. Use minImpact or domains to narrow."
}

Params: query (free text), yearFrom/yearTo (integers, negative = BCE), domains (enum array), minImpact (0–1), limit (1–200, default 20).

causal_chain

Trace cause→effect chains from a root event. The single most useful tool.

// arguments — "what did Docker enable?"
{ "event": "docker", "direction": "effects", "depth": 1 }

// response (trimmed)
{
  "root": { "id": "docker", "title": "Docker", "year": "2013" },
  "effects": [
    { "title": "Kubernetes", "relationship": "caused",      "confidence": 0.9,
      "evidence": "Kubernetes orchestrates Docker-style containers..." },
    { "title": "Microservices Architecture", "relationship": "enabled", "confidence": 0.8 }
  ],
  "relatedPatterns": [ { "pattern": "Abstraction Layer Migration", "predictiveValue": 0.8 } ]
}

Params: event (required — ID like "docker" or a title substring like "industrial"), direction (causes | effects | both, default both), depth (1–5, default 2), minConfidence (0–1). Returns { error } with a query_events hint when the event can't be resolved.

historical_resonance

Find historical patterns parallel to a present-day situation.

// arguments
{ "situation": "open protocol competing with a closed platform", "maxResults": 2 }

// response (trimmed)
{
  "matches": [
    { "pattern": "Open vs Proprietary Substrate", "matchScore": 0.35, "predictiveValue": 0.75,
      "exemplars": [ { "title": "TCP/IP", "year": "1983" }, { "title": "Linux Kernel", "year": "1991" } ] },
    { "pattern": "Information Democratization Cycle", "matchScore": 0.17, "predictiveValue": 0.85 }
  ]
}

Params: situation (required free text), domains (enum array), maxResults (1–20, default 3). Returns a hint when nothing matches.

predict_scenarios

Generate scenario branches from current conditions + historical patterns.

// arguments
{ "conditions": ["AI capability accelerating"], "domains": ["technology"], "horizon": 2040 }

// response (trimmed)
{
  "scenarios": [
    { "name": "Convergent Acceleration", "probability": 0.71, "historicalBasis": ["Substrate Substitution"] },
    { "name": "Constrained Progress",    "probability": 0.52 },
    { "name": "Discontinuous Shift",     "probability": 0.41 }
  ],
  "meta": { "matchedInsights": 5, "forecastEventsConsidered": 11,
            "disclaimer": "Scenarios are derived from historical pattern matching, not guaranteed forecasts." }
}

Params: conditions (required non-empty string array), horizon (integer year, default 2040), domains (enum array), maxScenarios (1–10, default 3). Treat output as structured hypotheses, not predictions.

org_knowledge (Enterprise tier)

Query an organization's private CKG. Returns an explanatory stub until an org graph is provisioned.

// arguments
{ "query": "database migration decisions", "orgId": "acme" }

// response
{
  "events": [], "causalContext": [], "available": false,
  "message": "No org-scoped knowledge graph configured for this org. Enterprise tier feature — see ADR-0004 Phase 4."
}

Params: query (required), orgId (required), team (optional), yearFrom/yearTo (optional integers).

Quick start

Option 1 — npm (recommended)

{
  "mcpServers": {
    "causari": { "command": "npx", "args": ["-y", "@causari/mcp-server"] }
  }
}

Add to .mcp.json (Claude Code project or ~/.claude/mcp.json global) or ~/.cursor/mcp.json (Cursor).

Option 2 — Hosted endpoint (no install)

Point directly to the hosted Cloudflare Worker — nothing to install or run locally:

{
  "mcpServers": {
    "causari": {
      "url": "https://mcp.causari.ai/mcp"
    }
  }
}

Works with any MCP client that supports HTTP transport (Claude Desktop, Cursor, Windsurf, etc.). The same Worker also serves GET /health (status + graph stats) and GET /.well-known/mcp.json (discovery manifest).

The hosted endpoint at mcp.causari.ai is the production target. Until it is live, use Option 1 (npx) or Option 3 (from source) — both run the identical server locally.

Option 3 — From source

git clone https://github.com/causari/mcp-server
cd mcp-server
pnpm install && pnpm build

{
  "mcpServers": {
    "causari": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/cli.js"]
    }
  }
}

Verify it works

In Claude Code:

Use the causari causal_chain tool to trace what led to the Transformer architecture, depth 3.

You should see a structured response with nodes, confidence scores, and an evidence chain — not just prose.

Status & roadmap

This is honest reporting, not marketing copy.

Current data depth (as of 2026-06):

• 245 events across 9 verticals: AI history, computing, web ecosystem, cloud/devops, databases, AI/ML tooling, security, mobile, and civilizational foundations
• 631 causal links with evidence text + confidence scores calibrated per-link
• 8 insight patterns (Abstraction Layer Migration, Standardization Cycle, Open vs Proprietary, Information Democratization Cycle, and more)

Strong coverage: Queries like causal_chain("docker"), causal_chain("reactjs"), causal_chain("jwt"), or historical_resonance("microservices vs monolith") return dense causal chains with evidence. Dev-term hit rate validated at 10/10.

Honest limitations:

• Confidence scores are curator estimates, not statistical posteriors.
• predict_scenarios is pattern-matching over the historical record, not probabilistic forecasting. Treat output as structured hypotheses, not predictions.
• Coverage outside the 9 current verticals is thinner. See causari/causari-data to request or contribute new verticals.

Roadmap:

• ✅ Cloudflare Worker HTTP transport — built, stateless, optional bearer auth (deploy pending)
• 🔜 Hosted endpoint live at mcp.causari.ai — deploy the Worker + attach the custom domain
• 🔜 API key + rate limiting — Pro tier
• 🔜 Embedding-based resonance — replace lexical match with semantic similarity
• 🔜 Org/Personal scope — user-curated private CKG via enterprise tier

Tests

pnpm test          # validation + worker transport + smoke (build included)
pnpm test:unit     # validation + worker transport only (no build)
pnpm smoke         # build, then the CKG query smoke test

pnpm test runs three suites:

• validation (25 cases) — every tool argument validator: type, range, NaN/Infinity, enum, empty-string, and domain-enum rejection.
• worker transport (18 cases) — the full MCP JSON-RPC flow plus hardening: content-type, body-size cap, batch rejection, malformed envelopes, unknown tools, and validation errors surfaced as isError results; auth on/off.
• smoke (12 cases) — CKG query correctness on known events (printing, transformer, chatgpt), fuzzy title resolution, and edge cases (missing event, depth cap), with a sample causal_chain printed.

Architecture

┌───────────────────────────────────────────┐
│  AI Agent (Claude Code, Cursor, Windsurf) │
└──────┬──────────────────┬─────────────────┘
       │ stdio (local)    │ HTTP/SSE (hosted)
       ▼                  ▼
┌──────────────┐  ┌─────────────────────────┐
│  cli.ts      │  │  worker.ts              │
│  (npx local) │  │  (Cloudflare Worker)    │
└──────┬───────┘  └────────────┬────────────┘
       │                       │
       └──────────┬────────────┘
                  ▼
┌──────────────────────────────┐
│  server.ts / tools.ts        │
│  - 5 tool definitions        │  ← output shaping, token-efficiency
│  - MCP request handlers      │
└──────────────┬───────────────┘
               │ imports
               ▼
┌──────────────────────────────┐
│  @causari/ckg                │
│  - types                     │  ← schema (Event, CausalLink, Insight)
│  - store                     │  ← in-memory + adjacency indexes
│  - query                     │  ← BFS, search, resonance, scenarios
│  - seed (9 verticals)        │  ← 245 events, 631 links, 8 patterns
└──────────────────────────────┘

Token-efficiency note: tool outputs drop redundant fields and inline relationship + evidence so the LLM doesn't have to re-query for context. Confidence + provenance is surfaced so the model can communicate uncertainty honestly to the user.

Contributing

The seed dataset is open under CC-BY-SA 4.0 in the causari/causari-data repo. See its CONTRIBUTING.md for event/link submission guidelines.

For server code contributions, file issues or PRs here.

License

This package is dual-licensed:

• Server code — MIT. See LICENSE. Do what you like.
• Bundled Causal Knowledge Graph dataset — CC-BY-SA 4.0. See NOTICE. Credit Causari and share derivatives alike. Source: causari/causari-data.

Ordinary use of the MCP tools by an agent does not trigger redistribution obligations; exporting or republishing substantial portions of the graph does. See NOTICE for details.

Related

• Causari Powflow Canvas — the same CKG, visualized for humans
• Architecture decisions are documented internally in the Causari monorepo
• Model Context Protocol — the open standard this server implements