Proxies AI agent requests to real FHIR servers (HAPI, SMART, Epic) through an MCP guardrail proxy with PHI redaction, audit trails, and URL rewriting. Use when connecting agents to production or sandbox EHR systems.
How this skill is triggered — by the user, by Claude, or both
Slash command
/healthclaw-guardrails:fhir-upstream-proxyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Connect to real FHIR servers while keeping the full MCP guardrail stack active.
Connect to real FHIR servers while keeping the full MCP guardrail stack active.
Client -> MCP Server -> Flask (guardrails) -> Upstream FHIR Server
|
redaction, audit, step-up,
tenant isolation, disclaimers,
URL rewriting
Set the FHIR_UPSTREAM_URL environment variable to enable proxy mode:
# HAPI FHIR R4 (open, no auth)
FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4 python main.py
# SMART Health IT (open, no auth)
FHIR_UPSTREAM_URL=https://r4.smarthealthit.org python main.py
# HAPI FHIR R5 (open, no auth)
FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR5 python main.py
# Local HAPI instance
FHIR_UPSTREAM_URL=http://localhost:8080/fhir python main.py
# Docker Compose with upstream
FHIR_UPSTREAM_URL=https://hapi.fhir.org/baseR4 docker-compose up -d --build
| Variable | Default | Description |
|---|---|---|
FHIR_UPSTREAM_URL | (empty) | Upstream FHIR server base URL. Enables proxy when set. |
FHIR_UPSTREAM_TIMEOUT | 15 | HTTP timeout for upstream requests (seconds) |
FHIR_LOCAL_BASE_URL | (empty) | Local server URL for URL rewriting in responses |
Fetched from upstream, then redacted + audited + disclaimers added. The agent never sees unredacted upstream data.
All query parameters forwarded to upstream. Results redacted per entry. Upstream's full search capabilities are available (chaining, _include, etc.).
Validated locally first (structural checks), then forwarded to upstream with step-up auth verification. Both local and upstream audit records created.
All upstream server URLs in responses are replaced with local proxy URLs. The agent and client never see the upstream server's hostname or paths.
/r6/fhir/health reports upstream connection status including FHIR version
and server software name.
Network errors return proper FHIR OperationOutcome responses, not stack traces.
| Server | URL | Auth | Status |
|---|---|---|---|
| HAPI FHIR R4 | https://hapi.fhir.org/baseR4 | None | Tested |
| SMART Health IT | https://r4.smarthealthit.org | None | Tested |
| HAPI FHIR R5 | https://hapi.fhir.org/baseR5 | None | Tested |
| Local HAPI | http://localhost:8080/fhir | None | Tested |
| Epic Sandbox | https://open.epic.com/Interface/FHIR | OAuth 2.0 | Limited |
The proxy uses httpx for HTTP client operations with:
application/fhir+json accept headerHealthClaw-Guardrails/1.0.0URL rewriting is recursive — it traverses the entire response JSON tree and replaces all occurrences of the upstream URL with the local proxy URL.
npx claudepluginhub aks129/healthclawguardrails --plugin healthclaw-guardrailsFHIR agent guardrails for clinical data access via MCP. Provides 12+ tools for reading/writing resources with automatic PHI redaction, audit trails, and step-up authorization.
Guides building FHIR R4 REST endpoints for Patient, Observation, Encounter, Condition, MedicationRequest including resource validation, HTTP status codes, value sets, coding systems (LOINC, SNOMED, RxNorm, ICD-10), and OperationOutcome error handling.
Provides FHIR development guidance including package management, resource modeling, server implementation, and terminology handling for R4, R4B, R5.