HealthClaw Guardrails
The security layer between AI agents and clinical data. A healthclaw.io open source project.
v1.1.0 | 266 tests | 12 MCP tools | FHIR R4 US Core v9 + R6 v6.0.0-ballot3 | Fasten Connect
FHIR standardized how health data is structured. MCP standardized how AI connects to tools.
Nobody standardized the guardrails in between. This project does.
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
AI Agent ──▶ MCP Server ──▶ Guardrail Proxy ──▶ Any FHIR Server
↓ (HAPI, Epic,
PHI redaction Medplum, etc.)
Audit trail
Step-up auth
Human-in-the-loop
Quick Start
# Install dependencies
uv sync
# Run (local mode with SQLite)
STEP_UP_SECRET=your-secret python main.py
# Run with upstream FHIR server
FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4 STEP_UP_SECRET=your-secret python main.py
# Open browser
open http://localhost:5000 # Landing page with live demo
open http://localhost:5000/r6-dashboard # Interactive dashboard
Docker
docker-compose up -d --build
# Services:
# - fhir-mcp-guardrails (Flask, port 5000)
# - agent-orchestrator (MCP server, port 3001)
# - redis (port 6379)
MCP Tools (12)
Read tools (no step-up required):
| Tool | Description |
|---|
context.get | Retrieve pre-built context envelopes |
fhir.read | Read a FHIR resource (redacted) |
fhir.search | Search with patient, code, status, date filters |
fhir.validate | Structural validation |
fhir.stats | Observation statistics (count/min/max/mean) |
fhir.lastn | Most recent N observations per code |
fhir.permission_evaluate | R6 Permission access control evaluation |
fhir.subscription_topics | List available SubscriptionTopics |
curatr.evaluate | Evaluate a FHIR resource for data quality issues |
Write tools (require step-up token):
| Tool | Description |
|---|
fhir.propose_write | Validate + preview without committing |
fhir.commit_write | Commit with step-up auth + human-in-the-loop |
curatr.apply_fix | Apply patient-approved fixes with Provenance tracking |
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:
- PHI Redaction — Agent reads a patient, receives redacted data
- $validate Gate — Agent proposes an Observation, validated before write
- Permission Deny — No Permission rule exists, access denied with reasoning
- Permission Permit — Permit rule created, re-evaluation succeeds
- Step-up + Human-in-the-loop — Write requires both token and human confirmation
- Commit + Audit — Write succeeds, full audit trail generated
Comparison
| Feature | This Project | AWS HealthLake MCP | Medplum MCP | Raw FHIR API |
|---|
| Works with any FHIR server | Yes | HealthLake only | Medplum only | N/A |
| PHI redaction on reads | Yes | No | No | No |
| Immutable audit trail | Yes | CloudTrail (separate) | Partial | No |
| Step-up auth for writes | Yes | IAM (separate) | Medplum auth | No |
| Human-in-the-loop | Yes | No | No | No |
| Permission $evaluate (R6) | Yes | No | No | No |
| Setup time | 10 seconds | 30+ minutes | 15+ minutes | Varies |
FHIR Version Support
| Version | Profile | Status | Resources |
|---|
| R4 | US Core v9 | Stable | Patient, Condition, AllergyIntolerance, Immunization, MedicationRequest, Procedure, DiagnosticReport, CarePlan, CareTeam, Goal, DocumentReference, Coverage, ServiceRequest, Location, Organization, Practitioner, PractitionerRole, RelatedPerson, Specimen, FamilyMemberHistory |
| R6 | v6.0.0-ballot3 | Experimental | Permission, SubscriptionTopic, DeviceAlert, NutritionIntake, DeviceAssociation, NutritionProduct, Requirements, ActorDefinition |
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
aks129