Fhir Upstream Proxy

FHIR Upstream Server Proxy

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

When to Use This Skill

• You need to connect an AI agent to a real FHIR server (HAPI, SMART, Epic)
• You want automatic PHI redaction on upstream server responses
• You need audit trails for agent access to production clinical data
• You want URL rewriting so upstream server details never leak to clients

Configuration

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

Environment Variables

| 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 |

What the Proxy Does

Reads

Fetched from upstream, then redacted + audited + disclaimers added. The agent never sees unredacted upstream data.

Searches

All query parameters forwarded to upstream. Results redacted per entry. Upstream's full search capabilities are available (chaining, _include, etc.).

Writes

Validated locally first (structural checks), then forwarded to upstream with step-up auth verification. Both local and upstream audit records created.

URL Rewriting

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.

Health Check

/r6/fhir/health reports upstream connection status including FHIR version and server software name.

Graceful Fallback

Network errors return proper FHIR OperationOutcome responses, not stack traces.

What the Proxy Does NOT Do

• No caching — every request hits the upstream server
• No SMART-on-FHIR auth forwarding — uses upstream's native auth model
• No cross-version translation — R4 responses stay R4
• No tenant isolation on upstream — enforced locally only
• No response transformation — upstream resources pass through as-is (after redaction)

Tested Upstream Servers

| 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 |

Proxy Implementation

The proxy uses httpx for HTTP client operations with:

• Configurable timeout (default 15 seconds)
• Automatic redirect following
• application/fhir+json accept header
• User-Agent identification: HealthClaw-Guardrails/1.0.0

URL rewriting is recursive — it traverses the entire response JSON tree and replaces all occurrences of the upstream URL with the local proxy URL.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aks129
• Source: aks129/HealthClawGuardrails
• License: MIT
• Homepage: https://www.healthclaw.io

Install and usage instructions live in the source repository linked above.