healthclaw-guardrails

Secure AI agent interactions with FHIR R4/R6 clinical data via MCP guardrails: proxy requests to EHRs with automatic PHI redaction on reads, step-up authorization for writes, immutable audit trails, tenant isolation; ingest from Epic/Cerner via Fasten, evaluate and correct data quality with Curatr, export de-identified health records.

HealthClaw Guardrails

The security layer between AI agents and clinical data. A healthclaw.io open source project.

FHIR standardized how health data is structured. MCP standardized how AI connects to tools. Nobody standardized the guardrails in between. This project does.

What's new in v1.3.0 — Wearables

Heart rate, HRV, SpO2, steps, sleep, BP, glucose, body weight — from Garmin, Oura, Polar, Suunto, Whoop, Fitbit, Strava, Ultrahuman — flow into HealthClaw as FHIR Observations with correct LOINC codes and device Provenance. Compiled Truth timelines now include wearable-sourced data; SmartHealthConnect's healthy-habits + diet-exercise skills read them through the same fhir_search they already use.

Open Wearables sidecar (the-momentum/open-wearables, MIT) runs under a new wearables docker-compose profile. It owns per-provider OAuth; we own the FHIR mapping.
r6/wearables/mapper.py translates 13 metrics to LOINC + UCUM FHIR Observations. Unknown fields fall through with code.text — no data loss.
Daemon poller syncs every WEARABLES_POLL_INTERVAL (default 900s), posts through /Bundle/$ingest-context with step-up + X-Agent-Id: wearable-sync.
wearables_sync_status MCP tool (16 tools total) returns connection status + _meta.ui.resourceUri pointing at the new Connection Manager MCP App.
MCP App at /r6/fhir/mcp-apps/wearables/ — cards per provider: connect / re-auth / sync / view.

Quick start: OPEN_WEARABLES_URL=http://open-wearables:8000 docker-compose --profile wearables up -d.

What's new in v1.2.0 — Compiled Truth

Every other health tool shows you data. HealthClaw shows you the trail.

GET /<type>/<id>/$compiled-truth — returns current redacted resource + curation state + quality score + full Provenance timeline (newest first).
fhir_compiled_truth MCP tool — agents call this before making resource-specific claims; responses carry _meta.ui.resourceUri pointing to an embeddable review surface.
MCP App at /r6/fhir/mcp-apps/compiled-truth/<type>/<id> — focused HTML page: current data, evidence timeline, approve / re-evaluate actions. Zero install.
Activated schema — curation_state (raw → in_review → curated) and quality_score (0.0–1.0) now persisted on every resource.
.health-context.yaml — single declaration of jurisdiction, audience, regulations, defaults. Read by the guardrail stack; mirrored in SmartHealthConnect.

What It Does

This is a vendor-neutral guardrail proxy that sits between any AI agent and any FHIR server. Every request passes through:

PHI redaction — Names truncated to initials, identifiers masked, addresses stripped, birth dates truncated to year
Immutable audit trail — Every read/write logged with tenant, agent, timestamp
Step-up authorization — HMAC-SHA256 tokens required for writes
Human-in-the-loop — Clinical writes blocked until a human confirms (HTTP 428)
Tenant isolation — Every query scoped to tenant, cross-tenant access blocked
Medical disclaimers — Injected on all clinical resource reads
Compiled Truth — Current state + append-only evidence trail for every resource

AI Agent ──▶ MCP Server ──▶ Guardrail Proxy ──▶ Any FHIR Server
                              ↓                    (HAPI, Epic,
                         PHI redaction              Medplum, etc.)
                         Audit trail
                         Step-up auth
                         Human-in-the-loop

Install as a Claude Plugin

HealthClaw ships as a Claude Code plugin marketplace. Two plugins are available:

# Add the marketplace
claude plugin marketplace add aks129/HealthClawGuardrails

# Install the FHIR guardrail plugin (this repo)
claude plugin install healthclaw-guardrails@healthclaw-marketplace

# Install the personal-health companion plugin (SmartHealthConnect)
claude plugin install smarthealthconnect@healthclaw-marketplace

Plugin	Skills	Source
`healthclaw-guardrails`	curatr, fasten-connect, fhir-r6-guardrails, fhir-upstream-proxy, healthex-export, phi-redaction	aks129/HealthClawGuardrails
`smarthealthconnect`	care-completion, diet-exercise, healthy-habits, kids-health, medication-refills, research-monitor	aks129/SmartHealthConnect

Each skill is auto-discoverable — Claude loads it when your prompt matches the skill's trigger phrases (e.g. "check my care gaps", "redact this bundle", "run Curatr on my conditions").

Quick Start

# Install dependencies
uv sync

# Run (local mode with SQLite)
STEP_UP_SECRET=your-secret python main.py