
dagstudio-mcp
com.blackswancausallabs/dagstudio-mcp
Causal DAG analysis: backdoor paths, adjustment sets, bias simulation. Validated against dagitty.
Documentation
dag-studio-mcp
Model Context Protocol (MCP) server for the DAG Studio causal-inference engine. It lets AI agents construct, analyze, and validate causal directed acyclic graphs (DAGs) using the same engine that powers the DAG Studio canvas.
Built and maintained by Black Swan Causal Labs. Listed in the RWE MCP Registry.
Tools
| Tool | What it does |
|---|---|
analyze_dag | Backdoor paths, minimal sufficient adjustment sets, identifiability |
parse_dagitty | Parse dagitty DSL (raw or R-wrapped) into the structured DAG model |
generate_code | R / Python analysis code for a DAG, plus a one-click DAG Studio URL |
check_overadjustment | Validate a proposed adjustment set: sufficiency (blocks every backdoor path) plus adjustment for mediators, colliders, and descendants of exposure |
simulate_data | Simulate data from a DAG under user-specified structural coefficients |
compute_bias | Empirical bias of an adjustment strategy against the simulated truth |
classify_effect_modification | Classify effect-modifier structure (direct, indirect, proxy, common-cause, pure interaction) |
get_canonical_example | Canonical teaching DAGs (confounding, M-bias, frontdoor, and others) |
validate_engine | Run the full canonical validation suite and report engine version |
Input and output conventions worth knowing:
- dagitty input. Tools that take a
dagitty_stringaccept the bare DSL (dag { ... }, as exported by dagitty.net) or the R call (dagitty('dag { ... }')), with quoted node names, chains, and{A B}groups. A bidirected edge (A <-> B) is converted to an explicit latent common cause and reported as anINPUT_REWRITTENflag. Undirected edges and anything else that cannot be represented as a DAG are errors; no statement is dropped silently. - Canonical DAG input. Node ids must be unique and every edge must reference a declared node. Declare unmeasured variables as nodes with
type: "latent". check_overadjustment.okis true only when the set is a valid adjustment set: it blocks every backdoor path (sufficient) and has no overadjustment problem. Paths left open are listed inopen_backdoor_paths.- Large DAGs. Identifiability is decided exactly at any size within the input caps. When there are too many eligible covariates to enumerate every subset,
analyze_dagreturns valid, irreducible sets and raisesIDENT_CANDIDATES_TRUNCATEDto say the list is not exhaustive.
Every analytical response carries an engine_version stamp, a concordance attestation, a diagnostics block with severity-coded flags, and citations to the underlying methods literature.
Validation
The engine is validated four ways for coherence: against Pearl (2009) theory, against the reference implementation dagitty (Textor et al. 2016), against DAG Studio's own analytical results, and empirically via compute_bias on simulated data.
- 35 canonical cases: T01 to T15 (structural identification) and EM01 to EM20 (effect modification), runnable live via
validate_engine. - A release-gate concordance check runs the engine head-to-head against dagitty (vendored at upstream commit
7a65777) and stamps the attestation surfaced in tool responses. - A randomized concordance check (
npm run concordance:fuzz) compares the engine with dagitty on several thousand seeded random DAGs and parser round-trips. Both checks run in CI on every push. - 107 unit and integration tests across the engine bindings, the tool layer, and the auth gate.
Hosted endpoint
The server runs as a Cloudflare Worker (Streamable HTTP):
https://dagstudio-mcp.blackswancausallabs.com/mcp
Access is token-gated during the trial period. Request a token at jdiazdecaro@blackswancausallabs.com. Tokens are accepted either as a bearer header or as a ?token= query parameter (the query form exists for clients whose connector UI cannot set custom headers, such as the Claude.ai web connector).
Claude Code:
claude mcp add --transport http dag-studio \
https://dagstudio-mcp.blackswancausallabs.com/mcp \
--header "Authorization: Bearer <your token>"
Claude.ai web: add a custom connector pointed at https://dagstudio-mcp.blackswancausallabs.com/mcp?token=<your token>.
Repository layout
dag-engine.js/dag-engine.d.ts: the analytical engine, a pure ESM module with no runtime dependenciessrc/tools/: one file per tool, each exporting{ InputSchema, OutputSchema, descriptor, handler }src/worker/: Cloudflare Worker transport and the token gate (auth.ts)src/index.ts: stdio entry point for local useci/: release-gate concordance harness against vendored dagittytests/: unit and integration tests (npm test)MCP_REQUIREMENTS.md: the v1 specificationFDA_GUIDANCE_ALIGNMENT.md: mapping of DAG Studio capabilities onto FDA draft RWE guidance protocol elements
The engine is developed alongside the DAG Studio canvas app and the vendored copy here is synced at release time. This repository is self-contained: clone it, npm install, and everything builds and tests without further setup.
Development
npm install
npm test # full suite
npm run dev # stdio server via tsx
npm run worker:typecheck # worker bundle typecheck
npm run worker:deploy # deploy (stamps engine_version from git HEAD first)
For interactive inspection: npx @modelcontextprotocol/inspector.
Protocol status
Built on @modelcontextprotocol/sdk (TypeScript). Current against the finalized MCP specification revision 2025-11-25. Migration to the 2026-07-28 revision is planned once stable SDK support ships.
License
Apache License 2.0 (see LICENSE).
Exception: ci/dagitty-src/ contains the dagitty reference engine (GPL-2.0, Textor et al.), vendored at upstream commit 7a65777 solely as a release-time CI fixture for the concordance check. It retains its own license, is excluded from the published npm package, and is not part of the deployed worker bundle.
No installation packages available.
Remote
Related Servers
com.blackswancausallabs/nhanes-mcp
Design-correct NHANES analysis: survey weights, pooled cycles, CIs and NCHS reliability flags.
com.blackswancausallabs/openfda-mcp
Resolve FDA application numbers and product names to regulatory metadata (CDER, CBER, CDRH).
com.blackswancausallabs/regintel-mcp
Retrieve FDA docket comments, attachments and draft/final guidance for reviewable analysis.