RootCause MCP

One case. One traceable ledger.

RootCause MCP is not a diagnostic model. It lets different Agents work from the same session, source contract, and output format while retaining every reasoning input, disconfirming item, limitation, and approval state.

01 Source inventory

Stable document IDs, hashes, time ranges, and de-identification state.

02 Atomic evidence

Verbatim snippets, source locations, event times, and verification methods.

03 Differential reasoning

Review every cell in a syndrome framework and build maximum reasonable breadth; three is only a finalization floor.

04 Systems analysis

Fishbone, 5-Why, HFACS, and conservative causation audit.

05 Human review

Preview first, approve later; retain reviewer identity and content hash.

For users and reviewers See who is responsible for what →

Understand why the Agent, MCP, and qualified reviewer cannot replace one another.

For Agent and MCP developers Go straight to contracts and gates →

Integrate with live schemas, tool profiles, and a preliminary-first workflow.

The Agent reasons; the MCP constrains and audits.

A conformant artifact comes from explicit handoffs of responsibility—not from dropping raw records into the MCP and expecting it to interpret them on its own.

01 · INPUT

Host / approved extractor

Reads raw PDFs, DOCX files, images, or EHR exports and emits atomic text, page or line locations, hashes, and time precision.

02 · REASON

Reasoning Agent

Expands mechanisms from phenotype and time course, audits every DDx cell, and supplies source-linked support, refutation, unknowns, and discriminators.

03 · GOVERN

Checks schemas, source lineage, evidence relations, state transitions, readiness gates, and standardized output.

04 · APPROVE

Qualified human reviewer

Reviews sources, medical plausibility, causal language, and corrective actions, then decides whether to approve a final snapshot.

01Create session

02Register manifest

03Review sources / evidence

04DDx / select lead

05Test both ways

06Biases / gaps

07RCA / HFACS review

08Preview report

09Human approval

The standard output is not a conclusion. It is a set of inspectable relationships.

The same case can be represented as JSON, Markdown, or a FHIR DiagnosticReport; canonical JSON is the handoff baseline. With locale=zh-TW and audience=clinician, built-in Markdown uses Traditional Chinese explanatory copy while preserving English diagnosis, test, drug, and procedure names.

Sources and timeline

Append-only source review and independence, document hashes, typed time, precision, and cross-source conflicts; unknown time is never falsely ordered.

Evidence and differential diagnosis

Item-level provenance, framework breadth audit, explicit leading selection, source-calibrated LR, support/refutation/neutral evidence, unknowns, discriminating tests, certainty, and must-not-miss disposition.

Systems RCA

Fishbone, 5-Why, authorized per-cause HFACS review, and causation audit; an audit status is not proof of causation.

Limits, readiness, and review

Unresolved gaps, cognitive biases, approver, approval scope, finalization blockers, and content hash.

case-analysis-report.json · illustrative abridged shape

{
  "source_inventory": [
    {
      "document": "SRC-001",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "evidence_count": 3,
      "verified_count": 3,
      "coverage_status": "reviewed",
      "de_identified": true,
      "independence_status": "independent",
      "source_group_id": "SRC-GROUP-001",
      "source_review_adjudication_id": "SRV-001",
      "source_reviewed_by": "authorized-reviewer",
      "source_reviewed_at": "2026-08-18T09:00:00Z",
      "source_review_reason": "Source lineage reviewed"
    }
  ],
  "hypotheses": [
    {
      "id": "HYP-001",
      "diagnosis": {"display": "Candidate A"},
      "mechanism_category": "VASCULAR",
      "diagnostic_role": "ETIOLOGIC",
      "certainty": "POSSIBLE",
      "reasoning_basis": "MECHANISM_INFERENCE",
      "must_not_miss": false,
      "supporting_evidence_ids": ["EVD-001"],
      "contradicting_evidence_ids": ["EVD-004"],
      "planned_tests": [],
      "status": "ACTIVE",
      "clinical_rationale": "Auditable rationale for Candidate A"
    },
    {
      "id": "HYP-002",
      "diagnosis": {"display": "Candidate B"},
      "mechanism_category": "DRUG_TOXIN_IATROGENIC",
      "diagnostic_role": "MIMIC",
      "certainty": "POSSIBLE",
      "reasoning_basis": "MECHANISM_INFERENCE",
      "must_not_miss": false,
      "supporting_evidence_ids": ["EVD-002"],
      "contradicting_evidence_ids": ["EVD-005"],
      "planned_tests": [],
      "status": "ACTIVE",
      "clinical_rationale": "Auditable rationale for Candidate B"
    },
    {
      "id": "HYP-003",
      "diagnosis": {"display": "Must-not-miss C"},
      "mechanism_category": "VASCULAR",
      "diagnostic_role": "ETIOLOGIC",
      "certainty": "UNKNOWN",
      "reasoning_basis": "MECHANISM_INFERENCE",
      "must_not_miss": true,
      "supporting_evidence_ids": ["EVD-003"],
      "contradicting_evidence_ids": [],
      "planned_tests": [{
        "test_id": "TST-001",
        "name": "Definitive local diagnostic study",
        "purpose": "RULE_OUT",
        "target_hypothesis_id": "HYP-003",
        "expected_supporting_result": "Predefined positive pattern",
        "expected_refuting_result": "Predefined adequate negative pattern",
        "status": "PLANNED"
      }],
      "status": "ACTIVE",
      "clinical_rationale": "Must-not-miss until ruled out"
    }
  ],
  "leading_hypothesis_id": "HYP-001",
  "root_causes": [{
    "id": "WHY-003",
    "answer": "Escalation trigger absent",
    "evidence": ["EVD-006"],
    "causation_verification_id": "AUDIT-001",
    "causation_result": "INSUFFICIENT_DATA",
    "disposition": "PROPOSED"
  }],
  "causation_verifications": [{
    "verification_id": "AUDIT-001",
    "cause_event": {"id": "WHY-003", "description": "Escalation trigger absent", "evidence": ["EVD-006"]},
    "effect_event": {"description": "Escalation was delayed", "evidence": ["EVD-007"]},
    "overall_result": "INSUFFICIENT_DATA",
    "audit_scope": "CONSERVATIVE_CAUSATION_AUDIT",
    "clinical_causality_established": false
  }],
  "conformance_checks": [{
    "code": "ROOT_CAUSATION_AUDIT_LINEAGE",
    "status": "PASS",
    "severity": "HARD",
    "message": "Root audit lineage is exact",
    "refs": ["WHY-003"],
    "details": {}
  }],
  "is_finalized": false,
  "content_hash": null
}

Treat it as a reasoning ledger, not a diagnostic model.

The MCP surface accepts structured actions; the application layer orchestrates the workflow; the domain layer protects medical-reasoning invariants; and the infrastructure layer persists sessions and artifacts.

Agent surface

Toolsstructured actions

Resourceslive contracts

Promptsworkflow guidance

Application

ServerStatesession aggregate

Handlersvalidation + orchestration

Readinesspreview-first gates

Domain

Evidence graphprovenance + links

Clinical reasoningDDx + Bayesian updates

Systems RCAFishbone + Why + HFACS

Persistence

SQLitelocal operational store

Checkpointsconfined recovery files

ExportsJSON + Markdown + FHIR

Review boundary

PRELIMINARYinspect and revise

Approval gateidentity + scope + time

Snapshotcontent-hashed handoff

Interface → Application → Domain ← Infrastructure

Live contracts are authoritative

Do not guess schemas by copying the website. The Agent should first read these MCP resources:

clinical://contracts/case-input-manifest
clinical://contracts/case-analysis-report
tools/list for the current tool schemas

Choose the tool profile for the task

condensed8

clinical25

rca24

all46

Counts are the 2.0.0a3 release snapshot; runtime tools/list takes precedence.

P0 deterministic conformance

A typed nested schema validates stable sections; the report carries conformance_checks[]
Sources require allowlisted append-only review, de-identification, and independence lineage; identical bytes are not two independent sources
Only a source-aware instant can be ordered or support temporality; date, range, relative, and unknown stay unpositioned
Root-audit ID, description, and evidence must exactly match the Why and evidence ledger
REJECTED entries cannot remain in the root-cause bucket; INSUFFICIENT_DATA is only PROPOSED
Choose a syndrome-appropriate framework; every cell in the PRIMARY breadth audit must be reviewed, with no NOT_ASSESSED
REVIEWED_INSUFFICIENT_DATA retains unknowns and typed discriminators and is not exclusion
Three unique DDx entries, two non-UNKNOWN mechanisms, and an applicable must-not-miss are finalization floors; every active DDx needs rationale, uncertainty, and genuine evidence or a typed test disposition
The lead must be explicitly selected; the leading and every must-not-miss diagnosis need genuine support plus contradiction or a typed planned test
A non-neutral LR must cross-link distinct verified LITERATURE calibration evidence; every Fishbone cause needs authorized HFACS review
Final requires an authorized reviewer, time, and recomputable hash, then becomes an immutable final snapshot
76/76 targeted hard-mutation regressions block unsafe finalization

Engineering-alpha deterministic P0 passed; Agent MVP is not established.

Contracts and targeted regressions show that nonconforming reports cannot finalize; the public cases and runner are engineering references only. They cannot establish DDx or root-cause correctness on unseen cases.

RootCause MCP 2.0.0a3 validation maturity (2026-08-19)
Validation layer	Current status	What it demonstrates
Engineering-alpha deterministic P0	Passed	Typed nested report schema, machine-readable `conformance_checks[]`, and 76/76 targeted hard-mutation regressions.
Native multi-source MCP flow	Passed	Multi-source manifest, exact provenance, DDx, RCA, approval gate, and unified report.
Public six-case corpus / runner	Engineering reference	Public cases scrubbed of filename, diagnosis, and LR leakage, plus a public rubric and runner scaffold; public gold is not a blinded evaluation.
Formal cross-Agent evaluation	NOT_ESTABLISHED	Requires 3 runtimes × 6 cases × 2 repeats = 36 runs, a repo-external private corpus, private holdout gold, clean data roots, and trusted server traces.
Two-clinician blinded review	NOT_ESTABLISHED	Requires two clinical reviewers to score DDx, must-not-miss, RCA, and causal language blindly, with adjudication of disagreements.
Production security / governance	NOT_ESTABLISHED	Identity, authorization, multi-tenancy, encryption, audit, and retention controls required in real deployments.

Finalized means “an immutable final snapshot that passed deterministic gates and carries an authorized reviewer, time, and recomputable hash.” It does not mean the diagnosis is clinically confirmed or causation is established. Reloading final JSON requires an operator-controlled reviewer allowlist; SHA-256 detects content changes but is not a digital signature.

What the engineering alpha establishes

typed nested contracts and fail-closed finalization
complete source-review ledger with a recomputed final inventory projection
root, Why, evidence, and audit lineage with safe dispositions
cell-complete syndrome-framework breadth audits and typed DDx dispositions; three entries are only a finalization floor
the public six-case corpus, rubric, and runner as engineering references

Formal Agent MVP: NOT_ESTABLISHED

a repo-external private corpus and private holdout gold
trusted runtime / MCP server traces and the 36-run matrix
blinded scoring by two clinical reviewers plus adjudication
PHI, IAM, audit, and retention controls

Start an engineering trial in five minutes.

Use synthetic or de-identified data first. Do not treat GitHub, CI, or public Pages as a secure clinical-data environment.

Install the locked environmentSynchronize runtime, development, and test dependencies.
Start with the condensed profileLet the Agent discover the 8 facade tools first.
Read the live contractsThen create the session and source manifest.
PRELIMINARY firstPreview blockers first; finalize only after qualified human review.
Validate the remote host separatelyRun the MCP doctor on the Agent or extension host that launches it.

terminal

# 1. Install the locked environment
uv sync --all-extras --all-groups --locked

# 2. Start the MCP server over stdio
ROOTCAUSE_TOOL_PROFILE=condensed uv run --locked rootcause-mcp

# 3. Verify both VS Code and Copilot configs on this host
uv run --locked python scripts/mcp_doctor.py --config all

# 4. The client should read these live resources first
clinical://contracts/case-input-manifest
clinical://contracts/case-analysis-report

Safety boundaries should appear before the feature list.

This is an engineering alpha. The public repository, CI, and GitHub Pages are not environments for receiving or retaining real clinical records.

Currently built in

stable source IDs, SHA-256, snippet, and location verification
data-path and checkpoint confinement
DDx, disconfirming evidence, conflict, readiness, and approval gates
PRELIMINARY / final state and content hash
JSON, Markdown, and FHIR DiagnosticReport output

Not built in / cannot be claimed

a built-in extractor for raw PDFs, DOCX files, images, or EHR exports
authentication, RBAC, multi-tenant isolation, at-rest encryption, or retention enforcement
guarantees of Agent clinical ability, error-free output, or regulatory compliance
proof of clinical causation from a causation audit
direct use in care decisions without human review