Frequently Asked Questions

No. In local/demo mode it stores JSON blobs in SQLite — purely for testing the guardrail patterns. In production use, you point it at a real FHIR server (HAPI, Epic, Medplum, AWS HealthLake) and it acts as a transparent proxy that enforces guardrails on every request going through.

All guardrails — PHI redaction, audit trail, step-up auth, human-in-the-loop — apply regardless of whether you're using local mode or a real upstream server.

Two profiles:

• FHIR R4 with US Core v9 — Stable, widely deployed US healthcare resources. AllergyIntolerance, Immunization, MedicationRequest, Procedure, DiagnosticReport, CarePlan, Coverage, and 13+ more types. These are safe for production use.
• FHIR R6 v6.0.0-ballot3 — Experimental ballot resources: Permission, SubscriptionTopic, DeviceAlert, NutritionIntake. These are for research and may change before R6 final release.

Both flow through the same guardrail stack.

Applied on every read path, including upstream FHIR server responses:

• Names → truncated to initials (Maria Elena Rivera → M. E. Rivera)
• Identifiers → masked to last 4 characters (MRN12345 → ***2345)
• Addresses → stripped to city, state, country only
• Birth dates → truncated to year only (1985-03-15 → 1985)
• Phone / email / telecom → fully removed
• Photos → removed

This is HIPAA Safe Harbor de-identification at the read layer. Data is stored unredacted; redaction happens at response time.

Reads are open (with tenant header). Writes require an additional HMAC-SHA256 signed token — the step-up token.

Tokens are generated at /r6/fhir/internal/step-up-token, signed with your STEP_UP_SECRET, include a 128-bit nonce, and expire after 5 minutes. They are tenant-bound — a token for tenant A cannot be used for tenant B.

This prevents an AI agent from autonomously writing clinical data without explicit human intent behind the token issuance.

Clinical resource writes (Observation, Condition, MedicationRequest, DiagnosticReport, AllergyIntolerance, Procedure, CarePlan, Immunization, NutritionIntake, DeviceAlert) return HTTP 428 Precondition Required unless the request includes the header X-Human-Confirmed: true.

This forces whatever system is issuing the write to explicitly set that header — meaning a human or human-authorized workflow confirmed the action. The AI agent cannot bypass this on its own.

Limitation: this is header-based, not cryptographic. A future version will use signed human-confirmation tokens.

Yes, at the application layer. SQLAlchemy event listeners fire on before_update and before_delete for AuditEventRecord and raise a RuntimeError, preventing any modification.

Every resource access — read, create, update, validate — writes an AuditEvent recording the tenant, agent, resource, and outcome. These cannot be modified through the application.

Note: a database administrator with direct SQL access could still modify records. For true immutability, store audit events in an append-only ledger or cloud audit service.

Model Context Protocol (MCP) is an open standard that lets AI agents connect to tools and data sources in a structured, describable way. Instead of writing custom API integrations for every AI framework, you expose your capabilities as MCP tools and any MCP-compatible agent can use them.

For health AI, this is significant: it means an AI agent can be connected to FHIR health data without you having to trust that agent with raw API keys, unrestricted data access, or unaudited writes. HealthClaw Guardrails is the security layer that makes that connection safe.

Read tools (no step-up required):

• context.get — Retrieve a pre-built, time-limited context envelope
• fhir.read — Read a resource (auto-redacted)
• fhir.search — Search with patient, code, status, date filters
• fhir.validate — Structural validation before any write
• fhir.stats — Observation statistics (count/min/max/mean)
• fhir.lastn — Most recent N observations per code
• fhir.permission_evaluate — R6 access control with human-readable reasoning
• fhir.subscription_topics — List SubscriptionTopics
• curatr.evaluate — Data quality evaluation for patient health records

Write tools (require step-up token + human confirmation for clinical types):

• fhir.propose_write — Validate and preview a write without committing
• fhir.commit_write — Commit with full guardrail enforcement
• curatr.apply_fix — Apply patient-approved data quality fixes with Provenance

Curatr is a patient-facing data quality skill. Your health records often contain coding errors — ICD-9 codes that were retired in 2015, missing required fields, or medication codes that don't match any known drug. These errors affect how AI tools interpret your health, and how insurers and providers see you.

Curatr evaluates your FHIR resources against live public terminology services (no account needed), explains issues in plain language with their real-world impact, and lets you approve fixes. Every approved fix creates a FHIR Provenance record with full attribution. It supports: Condition, AllergyIntolerance, MedicationRequest, Immunization, Procedure, DiagnosticReport.

The goal: your health data belongs to you. You should be able to see what's wrong with it and decide how to fix it.

HealthClaw is the data + guardrail layer. You chat with it through a gateway — anything that's an MCP client and renders responses in a UI you have. Four supported gateways today:

• OpenClaw — a Telegram bot. Fixed slash commands (/conditions, /labs, /curatr, /approve). Best if you only want one chat channel with predictable behavior.
• Hermes (Nous Research) — multi-gateway agent. Telegram + Discord + Slack + WhatsApp + Signal + CLI + HTTP. Self-improving: skills get better as you use them.
• PromptOpinion — a healthcare AI assembly platform. HealthClaw is published there as a Superpower + Agent; you "Add to Workspace" and chat in the browser.
• Claude Desktop / Claude Code — Anthropic's clients connect over native MCP. Use the published .mcp.json config or the hosted Railway URL.

All four use the same MCP server, the same skills library, and the same guardrails. Pick by where you want to type, not by what you can do.

Hermes is Nous Research's self-improving agent (github.com/nousresearch/hermes-agent). Two practical differences from OpenClaw:

• Many chat channels, one agent. OpenClaw is Telegram. Hermes is Telegram + Discord + Slack + WhatsApp + Signal + CLI + HTTP. Same persona, same skills, same MCP server — different surfaces.
• It learns. Hermes captures every conversation and lets you save working call patterns as skills, refine the persona on misfires, and search past sessions. The skills HealthClaw ships are starting points; Hermes refines them in ~/.hermes/skills/healthclaw/ as you use it.

OpenClaw and Hermes can run side-by-side. They share the same MCP server, so there's no migration cost.

Two commands once Hermes itself is installed:

git clone https://github.com/aks129/HealthClawGuardrails
cd HealthClawGuardrails
./hermes/install.sh

That installer is idempotent. It copies all skills to ~/.hermes/skills/healthclaw/, installs the HealthClaw SOUL.md persona at ~/.hermes/personas/healthclaw.md, and merges three MCP server entries (hosted demo, local Docker, SHARP-on-MCP) into ~/.hermes/config.json.

Then:

hermes
> /persona healthclaw
> show me my conditions

Full walkthrough including the three connection modes (hosted, local, SHARP) is on the Wiki — Hermes Quick Start. Flags: --dry-run previews; --skills-only refreshes just the skills if Hermes has edited them.

Same purpose, different ecosystem.

• AGENTS.md — OpenClaw's persona format. One per persona workspace (Sally-PCP, Mary-pharmacy, Dom-fitness, Kristy-scheduler).
• SOUL.md — Hermes' persona format. One per persona, loaded via /persona <name> at the start of a session.

HealthClaw ships its Hermes persona at hermes/SOUL.md. The installer puts it at ~/.hermes/personas/healthclaw.md. It covers tool selection, step-up token acquisition, the human-in-the-loop confirm flow, guardrail narration, and hard rules (no inventing FHIR resource types, no bypassing step-up auth, no claiming demo data is real).

The open standard for skill definitions that Hermes uses natively. A skill is a markdown file with YAML frontmatter declaring its name, description, references, optional tools list, and version. The body is a natural-language playbook.

HealthClaw's /skills directory ships ten of these — getting-started, curatr, fhir-r6-guardrails, phi-redaction, fhir-upstream-proxy, fasten-connect, healthex-export, healthex-export-redacted, personal-health-records, and hermes. They're auto-indexed at /skills on this site, and the same files install into both OpenClaw and Hermes.

Yes — both as an Agent and as an MCP Superpower. HealthClaw was the FHIR IQ team's submission to the PromptOpinion Agents Assemble Challenge on Devpost.

• Agent — HealthClaw Clinical Reviewer orchestrates the MCP tools and narrates what the guardrails did.
• Superpower (MCP server) — HealthClaw exposes 16 tools with the full guardrail stack.

Both listings are Open Access — no credentials to add to a PromptOpinion workspace. Click Add to Workspace, pick a model, start chatting. The hosted MCP server is seeded with synthetic Grover Keeling sample data so you can try everything without standing up anything locally.

SHARP-on-MCP (Standardised Healthcare Agent Remote Protocol) is a vendor-neutral spec for how an MCP server in healthcare receives its FHIR context. Instead of every MCP server running its own OAuth dance against every EHR, the agent host obtains a SMART-on-FHIR access token and forwards it on every call via three headers:

• X-FHIR-Server-URL — the upstream FHIR base (Epic, Cerner, MEDITECH, etc.)
• X-FHIR-Access-Token — the SMART access token
• X-Patient-ID — optional patient banner / launch context

HealthClaw's MCP server advertises SHARP compliance in its initialize response under capabilities.experimental.{fhir_context_required, sharp}, and PromptOpinion compliance under capabilities.extensions["ai.promptopinion/fhir-context"]. Both specs use the same headers, so one HealthClaw deployment works against any SMART-launched agent host in either ecosystem.

Set the FHIR_UPSTREAM_URL environment variable:

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

All guardrails remain active. Reads are fetched from upstream, redacted, and audited. Writes are validated locally first, then forwarded with step-up auth enforcement. Upstream URLs never leak to clients.

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

Required in production:

• STEP_UP_SECRET — HMAC secret for step-up tokens. Auto-generated on Vercel.
• SQLALCHEMY_DATABASE_URI — Use PostgreSQL in production (default: SQLite)

Optional:

• FHIR_UPSTREAM_URL — Connect to a real FHIR server
• SESSION_SECRET — Flask session key
• FHIR_UPSTREAM_TIMEOUT — Upstream request timeout in seconds (default 15)
• REDIS_URL — For rate limiting and sessions (default: redis://redis:6379/0)

The guardrail patterns are production-grade. The local storage mode (SQLite JSON blobs) is not — it lacks indexed search, horizontal scaling, and proper query performance. For production:

• Use upstream proxy mode pointing at a real FHIR server
• Set a strong STEP_UP_SECRET
• Use PostgreSQL for the audit database
• Enable Redis for rate limiting
• Deploy behind HTTPS

The human-in-the-loop mechanism is currently header-based, not cryptographically signed. Treat it as a pattern demonstration rather than a production-grade confirmation mechanism.