Healthclaw Guardrails

What it is: an open reference implementation of the FHIR × MCP guardrail layer — PHI redaction, immutable audit, step-up auth, and tenant isolation — that sits between any AI agent and any FHIR server. Built in the open as a community project, MIT-licensed. Not a product, not a pitch: if the pattern is useful, take it; if it's wrong, tell us or fix it.

This is a community effort. It's most useful when implementers, clinicians, and standards folks poke holes in it. Issues, PRs, and "you got the SDC extraction wrong" critiques are all welcome — start with CONTRIBUTING.md and the Code of Conduct.

At a glance: v2.1.0, with 4,000+ Python and 200+ Node tests across 29 MCP tools. CareAgents is the hosted consumer app: passkey sign-in, advisors, and chat on the web. iMessage works where it's offered; Telegram is not open in the beta. Two rails run end to end — real-world actions behind a provably out-of-band gate, and forms ($populate → human review → provenance PDF). Standards: FHIR R4 US Core v9 and R6 v6.0.0-ballot3, HL7 SDC forms, NQF 0018. Operations: lab interpreter ($interpret), care-gaps reminders ($care-gaps) with an embedded MCP-App view, and ChatGPT-connector search/fetch. Connectors: Fasten TEFCA, HealthEx, HBO, Flexpa, Epic, MEDENT, Open Wearables, SMART Health Links. Also a Claude Code plugin and OpenAI/Gemini adapters.

Try it in 60 seconds — no clone, no keys

The hosted demo runs synthetic data behind the full guardrail stack:

# Watch the deployment grade its own guardrails (PHI redaction, audit, step-up, ...):curl "https://app.healthclaw.io/r6/fhir/\$conformance?format=text"

Point any MCP client at the public demo server — URL https://mcp-demo-production-ee2c.up.railway.app/mcp, no key required — then ask: "Search my health records for lab results and explain them in plain language." The demo server is unauthenticated but hard-pinned to a synthetic demo tenant, so it can only ever serve fake data. A separate production endpoint (mcp-server-production-5112) requires a deployment-scoped Authorization: Bearer <token> — real records stay behind auth, always. Hosted connectors cannot attach that header, so the demo URL above is the one to paste. One-command installs: gemini extensions install https://github.com/aks129/HealthClawGuardrails · claude plugin marketplace add aks129/HealthClawGuardrails · skills on ClawHub

Non-developer? Step-by-step guides for Claude (web/desktop/phone), Perplexity, ChatGPT, Grok, Meta Muse and Telegram — plus a 10-minute demo script — in docs/quickstarts/.

Listed in: Official MCP Registry (io.github.aks129/healthclaw-guardrails) · Glama (hosted connector) · ClawHub (14 skills) · Gemini CLI Extensions · agent-skills discovery at /.well-known/agent-skills/

Release highlights

Full notes live in Releases.

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, identifier values removed (system and type kept), 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 — real-world actions (calls, SMS, forms): commit only submits. Execution requires a provably out-of-band single-use approval bound to the action, which the agent's own toolchain cannot satisfy. Direct clinical FHIR writes answer HTTP 428 until an X-Human-Confirmed header is present. The caller sets that header, so it is not a human gate: a known gap tracked in #214
• 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

How it differs from a plain FHIR MCP server

Direct clinical FHIR writes are the exception to the approval row: they still gate on a header the caller sets (#214).

Prove it: guardrail conformance

The guardrails are verifiable, not marketing. A runnable harness probes any deployment with synthetic data and emits a scorecard across all seven properties — run it against your own instance (or ours):

python scripts/guardrail_conformance.py \  --base-url https://app.healthclaw.io --tenant desktop-demo \  --step-up-token "$(mint a token via POST /r6/fhir/internal/step-up-token)"

HealthClaw Guardrail Conformance — https://app.healthclaw.io [tenant=desktop-demo]  Grade: A   (7/7 properties)  [PASS] PHI Redaction            [PASS] Human-in-the-Loop  [PASS] Immutable Audit Trail    [PASS] Tenant Isolation  [PASS] Step-Up Authorization    [PASS] Medical Disclaimers  [PASS] Error Fidelity — A (local-fhir-only)

Or hit the one-URL self-test on any running deployment — no token needed, it self-tenants internally and returns 200 at Grade A (503 otherwise):

curl "https://app.healthclaw.io/r6/fhir/\$conformance?format=text"

The local FHIR profile is Grade A: unsupported local-search inputs are rejected or reported according to Prefer: handling, and every failure path is audited. The same harness runs against the Flask test client as a CI baseline (tests/test_guardrail_conformance.py). --json emits a machine-readable report; --mcp-url additionally grades MCP tools/call error signaling as a separate profile. For an authenticated MCP deployment, set MCP_AUTH_TOKEN or pass --mcp-auth-token. Library API: from r6.conformance import LiveProbeClient, ProbeContext, run_conformance.

What this grade means (and what it doesn't)

The grade covers the HealthClaw guardrail layer only — a self-test of the seven properties against synthetic data it just created. It is not a HIPAA Security Rule assessment, a third-party audit, or a penetration test of your deployment: infrastructure, BAAs, encryption at rest/in transit, and access controls remain the deployer's responsibility (see Known Limitations). Because the harness is deployment-agnostic, a third party can run it against any instance as one input to a real assessment — it does not substitute for one. The report states this scope itself in every output format.

Install as a Claude Plugin

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

# Add the marketplaceclaude 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 (frozen — upstream archived)claude plugin install smarthealthconnect@healthclaw-marketplace

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").

Not on Claude/MCP? The same 28 guardrailed tools run on OpenAI, Gemini, LangChain, or plain HTTP via the framework-neutral bridge in adapters/ — see Recipe: run HealthClaw tools on any agent framework. Guardrails stay server-side, so no framework can bypass them.

Quick Start

# Install dependenciesuv sync
# Apply deterministic database migrationsSTEP_UP_SECRET=your-secret uv run flask --app main init-dbSTEP_UP_SECRET=your-secret uv run flask --app main seed-demo --tenant-id desktop-demo
# Run (local mode with SQLite)STEP_UP_SECRET=your-secret python main.py
# Run with upstream FHIR serverFHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4 STEP_UP_SECRET=your-secret python main.py
# Open browseropen http://localhost:5000            # Landing page with live demoopen http://localhost:5000/r6-dashboard  # Interactive dashboard

Docker

docker-compose up -d --build
# macOS note: port 5000 conflicts with AirPlay Receiver — remap with:# HOST_PORT=5050 docker-compose up -d --build
# Services:# - fhir-mcp-guardrails (Flask, port 5000)# - agent-orchestrator (MCP server, port 3001)# - redis (port 6379)

MCP Tools (29)

Tool names use underscores (not dots) for Claude Desktop / MCP client compatibility.

Read tools (no step-up for public tenants):

Write tools (require step-up token):

Utility tools:

All tools add _mcp_summary with reasoning, clinical context, and limitations.

Guardrail Demo

The 6-step demo at /r6/fhir/demo/agent-loop shows the full guardrail sequence:

1. PHI Redaction — Agent reads a patient, receives redacted data
2. $validate Gate — Agent proposes an Observation, validated before write
3. Permission Deny — No Permission rule exists, access denied with reasoning
4. Permission Permit — Permit rule created, re-evaluation succeeds
5. Step-up + Human-in-the-loop — Write requires both token and human confirmation
6. Commit + Audit — Write succeeds, full audit trail generated

Comparison

FHIR Version Support

Both R4 and R6 resources flow through the same guardrail stack (PHI redaction, audit, step-up auth, tenant isolation). R6 ballot resources may change before final release.

Testing

# Python tests (1,490+ across 90+ files; includes action-rail, SDC, quality, labs, ops, CareAgents suites)uv run python -m pytest tests/ -vuv run python -m pytest tests/test_r6_routes.py::test_name -v   # single test
# MCP server testscd services/agent-orchestrator && npm ci && npm test
# Playwright end-to-end tests (UI + API, requires Flask on :5000)cd e2e && npm ci && npx playwright install --with-deps chromium && npm testcd e2e && npm run test:headed    # headed browsercd e2e && npm run test:ui        # interactive UI mode

API Endpoints

Local search accepts the parameters advertised by /r6/fhir/metadata. Unknown parameters default to lenient handling (a bounded search.mode="outcome" warning); Prefer: handling=strict returns a 400 OperationOutcome. Unsupported modifiers and malformed supported values always return 400. _count=0 and _summary=count are count-only searches. Self links contain exactly the applied, URL-encoded parameters, and audit output never echoes submitted filter values or arbitrary parameter names.

Upstream Proxy

Connect to real FHIR servers while keeping all guardrails active:

FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4 python main.py

• Reads: Fetched from upstream, then redacted + audited + disclaimers added
• Searches: Forwarded with all query params, results redacted per entry
• Writes: Validated locally first, then forwarded with step-up auth check
• URL rewriting: Upstream URLs never leak to clients

Tested with: HAPI FHIR R4/R5, SMART Health IT, Epic Sandbox.

Put the guardrails in front of your FHIR server — recipe for running the redaction + audit + step-up + human-in-the-loop stack in front of Medplum (the same pattern works for Aidbox, Google Cloud Healthcare, or any FHIR R4 server): docs/recipes/healthclaw-in-front-of-medplum.md. A repeatable integration test (tests/test_medplum_in_front.py) proves a Medplum-returned Patient comes back redacted + audited and writes are step-up gated before reaching Medplum.

Curatr — Patient-Owned Data Quality

Curatr is a patient-facing data quality skill that evaluates FHIR health records for coding issues and lets the patient decide how to resolve them.

1. Patient connects data → HealthClaw Guardrails deidentifies and loads it2. OpenClaw calls curatr.evaluate → checks codes against live terminology APIs3. Issues presented in plain language with impact and fix suggestions4. Patient approves fixes → curatr.apply_fix updates resource + creates Provenance5. Optional: generate a structured correction request for the source provider

What Curatr checks on a Condition:

Every fix creates a linked Provenance resource recording patient intent, field changes, and agent attribution. All changes are audited in the immutable trail.

OpenClaw skill: skills/curatr/SKILL.md

SMART Health Links (Kill the Clipboard)

Patient-controlled encrypted record sharing via QR code, implemented on top of jmandel/kill-the-clipboard-skill (MIT, pinned fa0020d) — credit Josh Mandel. HealthClaw governs what enters the bundle (step-up auth, profiles, guardrails, audit trail); KTC governs sharing (zero-knowledge server-side storage, SHL STU 1 protocol, revocation, in-browser viewer).

Off by default. shl_generate is withheld from tools/list and a call is refused unless the operator sets MCP_ENABLE_SHL_GENERATE=true. Patient-initiated sharing is being rebuilt behind a consent page.

What it does: The shl_generate MCP tool (Write group, step-up required) fetches the patient's guardrailed FHIR bundle, encrypts it client-side in the MCP server (the SHL server never sees plaintext), uploads ciphertext, and returns:

• shlink — the shlink:/ URI to encode in a QR (an encrypted pointer, not data)
• viewer_link — browser URL for clinic staff
• manage_link — patient-only revocation + access-log URL

Security: The QR encodes only the encrypted pointer. PHI never appears in the QR image. The SHL server stores only ciphertext + sha256(auth_token). Persona hard rule: see skills/share-health-qr/SKILL.md — never direct-encode PHI into QR images (incident 2026-06-12).

Quick Start (local)

# Start the SHL storage server (profile `shl`)docker-compose --profile shl up -d
# Tell the MCP server where the SHL server lives# Add to services/agent-orchestrator/.env or export:export SHL_SERVER_URL=http://localhost:8000

Without SHL_SERVER_URL, shl_generate returns an explicit simulation stub (simulated: true) — never a fake link.

Railway Deploy

# 1. Add the SHL servicerailway add --service shl-server
# 2. Attach a persistent volume (SQLite lives here)railway service shl-server && railway volume add --mount-path /data
# 3. Configure the SHL serverrailway variables --service shl-server \  --set BASE_URL=<public-url-of-shl-server> \  --set DB_PATH=/data/db.sqlite
# 4. Expose a public domainrailway domain --service shl-server
# 5. Deploy — MUST run from the shl-server directorycd services/shl-server && railway up --service shl-server
# 6. Wire the MCP server to the SHL serverrailway variables --service mcp-server \  --set SHL_SERVER_URL=<public-url-of-shl-server>

Caveat 1 — deploy from the right directory: The repo-root railway.toml targets the Flask Dockerfile. If you run railway up --service shl-server from the repo root, Railway uses the wrong Dockerfile and the deploy fails. Always cd services/shl-server first — that directory has its own railway.toml that points to the correct image.

Caveat 2 — watchPatterns skip: A service that inherited watchPatterns from the root config may silently skip Dockerfile-only deploys (no source file changes detected). The per-service railway.toml in services/shl-server/ overrides this after the first successful build. If deploys are skipped, force one with railway up --service shl-server from the shl-server directory.

Caveat 3 — simulation mode: Without SHL_SERVER_URL on the MCP server, shl_generate returns { simulated: true, note: "SHL_SERVER_URL not configured — returned stub." }. Personas surface this note verbatim and never improvise an alternative.

OpenClaw skill: skills/share-health-qr/SKILL.md

R6-Specific Resources (Experimental)

These resources are part of the FHIR R6 ballot3 specification and may change before final release.

US Core v9 R4 Resources (Stable)

Standard FHIR R4 resources conforming to US Core Implementation Guide v9. These are widely deployed in US healthcare and stable for production use.

AllergyIntolerance, Immunization, MedicationRequest, Medication, MedicationDispense, Procedure, DiagnosticReport, CarePlan, CareTeam, Goal, DocumentReference, Location, Organization, Practitioner, PractitionerRole, RelatedPerson, Coverage, ServiceRequest, Specimen, FamilyMemberHistory

Environment Variables

Database DDL is never run during WSGI import. Run flask --app main init-db before each release; it applies the locked Alembic revisions. Operators adopting Alembic on an existing v1.8.0 Postgres deployment must follow the database migration runbook to verify and stamp the compatibility baseline before upgrading.

Project Structure

main.py                         Flask app entry pointapp.py                          Web UI routes (landing, dashboard)r6/  routes.py                     R6 FHIR REST Blueprint (1,732 lines)  models.py                     R6Resource, ContextEnvelope, AuditEventRecord  validator.py                  FHIR R6 structural validation  redaction.py                  PHI redaction (names, identifiers, addresses, DOB, telecom)  audit.py                      Immutable AuditEvent recording  stepup.py                     HMAC-SHA256 step-up token management  oauth.py                      OAuth 2.1 + PKCE + SMART-on-FHIR discovery  health_compliance.py          Disclaimers, HITL, de-identification preview, audit export  context_builder.py            Bundle ingestion + context envelopes  rate_limit.py                 Per-tenant rate limiting  fhir_proxy.py                 Upstream FHIR server proxy with URL rewriting  curatr.py                     Curatr data quality engine (terminology lookups + fix application)services/agent-orchestrator/  src/index.ts                  MCP server (Streamable HTTP + SSE)  src/tools.ts                  12 tool definitions + executor (incl. curatr.evaluate, curatr.apply_fix)e2e/                            Playwright end-to-end teststemplates/                      Jinja2 (landing page, dashboard)static/                         CSS + JS for interactive dashboardskills/curatr/                  Curatr OpenClaw skill definitiontests/                          266 pytest tests (8 files, incl. test_us_core_r4.py)

Personal FHIR data store — patient import flow

This walkthrough shows how to go from a raw HealthEx export to querying your own records through Claude Code's MCP tools.

1. Start the stack

uv syncuv run python main.py                         # Flask on :5000cd services/agent-orchestrator && npm ci && npm start  # MCP on :3001

2. Import your HealthEx / Flexpa / generic FHIR bundle

# Dry-run first to preview without writingpython scripts/import_healthex.py \  --bundle-file ~/Downloads/my-records.json \  --dry-run
# Real import — prints context_id on successpython scripts/import_healthex.py \  --bundle-file ~/Downloads/my-records.json \  --tenant-id my-patient \  --step-up-secret "$STEP_UP_SECRET"

3. Connect Claude Code via MCP

.mcp.json in this repo auto-configures Claude Code when you open the project. Update X-Tenant-ID to match your --tenant-id:

{  "mcpServers": {    "healthclaw-local": {      "type": "http",      "url": "http://localhost:3001/mcp",      "headers": { "X-Tenant-ID": "my-patient" }    }  }}

Then in Claude Code:

Use fhir_search to find all my ConditionsUse context_get with context_id <ctx-id> to get my full context envelopeUse curatr_evaluate on Condition/<id> to check data quality

4. Set up Fasten Connect (optional)

# .env additionsFASTEN_PUBLIC_KEY=<key>FASTEN_PRIVATE_KEY=<key>FASTEN_WEBHOOK_SECRET=<secret>FASTEN_CURATR_SCAN=true    # auto-run Curatr after each import

Records arrive via webhook at /r6/fasten/webhook and are stored under the patient's canonical tenant ID.

5. Deidentify for sharing

# De-identification preview (not a legal Safe Harbor determination)curl -H "X-Tenant-ID: my-patient" \  http://localhost:5000/r6/fhir/Patient/pt-1/\$deidentify
# Patient-controlled (preserves birthDate, strips institutional identifiers)curl -H "X-Tenant-ID: my-patient" \  "http://localhost:5000/r6/fhir/Patient/pt-1/\$deidentify?mode=patient-controlled&patient_id=my-patient"

6. Telegram bot (optional)

TELEGRAM_BOT_TOKEN=<token> TENANT_ID=my-patient \FHIR_BASE_URL=http://localhost:5000/r6/fhir \python openclaw/bot.py

Commands: /health, /conditions, /labs, /curatr, /curatr fix, /approve.

Or via Docker Compose:

docker-compose --profile openclaw up -d

7. Use Medplum as the backing FHIR store (optional)

Set in .env (leave FHIR_UPSTREAM_URL empty):

MEDPLUM_BASE_URL=https://api.medplum.com/fhir/R4MEDPLUM_CLIENT_ID=<id>MEDPLUM_CLIENT_SECRET=<secret>

All guardrails apply to Medplum responses identically to local SQLite mode. Access tokens are cached in Redis (key medplum:access_token; falls back to in-process cache when Redis is unavailable).

Known Limitations

• The conformance grade is a self-test of the guardrail layer, not a HIPAA assessment or third-party audit — see What this grade means
• Local mode: JSON blob storage with table-scan search (no indexed fields)
• Redaction is HIPAA Safe-Harbor-style field redaction (demographics), not Expert Determination. It's a compensating control that removes identifier-class fields (identifier values are removed outright, not truncated); it is not a legal de-identification determination. Production de-id rigor (profile-specific recursive allowlists, an Expert-Determination path) is on the roadmap (#112).
• Validation is structural, not full StructureDefinition/profile conformance or terminology binding. What's demonstrated is the guardrail contract (redact + audit + step-up + human-confirm + tenant isolation + error fidelity), not production validation depth — that's tracked in #112.
• SubscriptionTopic stored but notifications not dispatched
• Direct clinical FHIR writes have no real human gate. They answer HTTP 428 until the caller sends X-Human-Confirmed, and the caller sets that header about itself, so it proves nothing about a human. This is a known gap (#214); do not build on it. The real human gate is the action rail, used by real-world actions (phone/SMS/forms), and it does not accept that header. commit only submits the action for out-of-band approval (202 awaiting_confirmation). The patient's Approve tap consumes a single-use ActionConfirmation credential server-side before anything executes.
• OAuth endpoints are for discovery/SMART advertisement; route enforcement is via step-up + read-auth tokens, and the auto-approve authorize flow is limited to public/demo tenants (no per-user consent screen)
• No historical versioning (version_id increments but old versions not retrievable)
• Upstream proxy: no response caching, no cross-version translation
• Security is config-dependent — production requires READ_AUTH_ENABLED=true (authenticate non-public reads), INTERNAL_TOKEN_MINT_SECRET (gate token mint/seed for non-public tenants; fail-closed in prod when unset), PUBLIC_TENANTS limited to synthetic demo tenants, a real SESSION_SECRET/STEP_UP_SECRET, and https-only upstreams
• Step-up tokens are valid for multiple writes within their 5-min TTL (not single-use); irreversible actions rely on state-machine idempotency (guarded WHERE status='proposed' claim) rather than nonce consumption

Contributing — this is a community effort

HealthClaw Guardrails is developed in the open as a shared reference, not a commercial product. The guardrail layer between AI agents and clinical data only gets trustworthy if a lot of people with different vantage points pressure-test it. We especially want:

• Implementers building FHIR × MCP integrations — tell us where the patterns break in the real world.
• Clinicians & compliance folks — challenge the redaction profiles, audit model, and the documented HIPAA postures.
• Standards people (HL7 / SDC / SMART) — tell us where we've diverged from the spec, especially on $populate/$extract.
• Anyone — open an issue, file a "you got this wrong," or send a PR.

Start here: CONTRIBUTING.md · Roadmap · Dev Guide · Code of Conduct · CHANGELOG.md · Security policy

Good first contributions are labeled in the issue tracker. Contributions are DCO-signed (git commit -s) under the MIT license — see LICENSING.md for the project's licensing posture going forward.

Community

• GitHub Discussions — questions, ideas, show-and-tell.
• good first issues — scoped, ~15-minute-to-start contributions.
• Building on OpenClaw or Hermes? The skills are on ClawHub; the MCP server is in the Hermes catalog.

License

MIT — free to use, fork, and build on. See LICENSE.