# Fhir Upstream Proxy

> >

- **Type:** Skill
- **Install:** `agentstack add skill-aks129-healthclawguardrails-fhir-upstream-proxy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aks129](https://agentstack.voostack.com/s/aks129)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aks129](https://github.com/aks129)
- **Source:** https://github.com/aks129/HealthClawGuardrails/tree/main/skills/fhir-upstream-proxy
- **Website:** https://www.healthclaw.io

## Install

```sh
agentstack add skill-aks129-healthclawguardrails-fhir-upstream-proxy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
# 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](https://github.com/aks129)
- **Source:** [aks129/HealthClawGuardrails](https://github.com/aks129/HealthClawGuardrails)
- **License:** MIT
- **Homepage:** https://www.healthclaw.io

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aks129-healthclawguardrails-fhir-upstream-proxy
- Seller: https://agentstack.voostack.com/s/aks129
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.