The security layer between AI agents and clinical data — a healthclaw.io open source project.
fhir.propose_write. Structural validation gate runs. Resource previewed without committing.$evaluate returns permit or deny with reasoning. No matching rule = default deny.X-Human-Confirmed: true.Applied on every read path — direct reads, search results, upstream proxy responses, and context envelopes. The agent never has access to raw patient data.
name: Maria Elena Rivera
mrn: MRN-2026-4471
phone: 617-555-0198
address: 123 Clinical Ave
Boston, MA 02101
dob: 1985-03-15
name: M. E. Rivera mrn: ***4471 phone: [Redacted] address: Boston, MA dob: 1985
Tenant isolation enforced at the database layer on every query. HMAC-SHA256 step-up tokens for writes. ETag/If-Match concurrency control. OAuth 2.1 with PKCE (S256 only). Append-only audit trail with database-level immutability.
Read tools return _mcp_summary with reasoning and clinical context. Writes use propose/commit: fhir.propose_write validates first, fhir.commit_write requires step-up auth. Curatr tools evaluate and fix patient record quality.
Clinical writes return HTTP 428 without explicit human confirmation. HIPAA Safe Harbor de-identification on demand. Medical disclaimer injected on clinical reads. PHI redaction on all read paths including upstream proxy responses.
| Flask App | FHIR REST at /r6/fhir/*, guardrail enforcement |
| MCP Server | Node.js + TypeScript — 12 tools, Streamable HTTP + SSE |
| Fasten Connect | Patient-authorized EHR ingestion via /fasten/webhook |
| Storage | SQLite (dev) / PostgreSQL (prod) — 37 FHIR resource types |
| Validation | Structural: US Core v9 required fields + R6 value constraints |
| Local mode | JSON blobs in SQLite — zero-config for development |
| Upstream proxy | Any FHIR server (HAPI, SMART Health IT, Epic) — set FHIR_UPSTREAM_URL |
| Fasten Connect | Patient-authorized bulk EHI import from 1000+ EHR systems |
| TEFCA IAS | Single identity verification → longitudinal record across all QHINs |
HealthClaw Guardrails was built from personal experience navigating a broken health data system. These articles share the thinking, the frustrations, and the vision behind the project.