healthclaw-marketplace

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:

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

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