PriorAuth Agent

AI-powered prior authorization orchestration over FHIR patient records, exposed as MCP tools and an A2A-discoverable agent.

!Track 1: MCP Superpower !Track 2: A2A Agent !MCP !FHIR R4 !TypeScript !Next.js !Claude !Docker !License: MIT

---

Overview

PriorAuth Agent automates the healthcare prior authorization workflow from coverage determination to appeal drafting. Given a FHIR patient ID and a procedure code, it checks payer requirements, gathers clinical evidence from FHIR records, evaluates that evidence with Claude, assembles a PA package, and can draft a denial appeal with additional evidence.

This is not a chatbot wrapper. The system exposes structured MCP tools and an A2A Agent Card, produces auditable reasoning traces, streams real-time workflow events to a demo UI, and keeps a clinician approval gate in the loop.

The Problem

Prior authorization remains one of the largest administrative burdens in US healthcare:

| Burden | Evidence | |--------|----------| | $31B annual administrative cost | CAQH Index | | 34 hours per physician per week | AMA prior authorization survey | | 94% of physicians report care delays | AMA | | 14.6 days average processing time | AMA | | 1 in 3 requests initially denied | Industry benchmarks |

Traditional rules engines can identify that a code requires PA. They cannot reliably decide whether a patient's chart actually satisfies criteria such as recent imaging severity, adequate conservative therapy, or validated functional impairment. PriorAuth Agent addresses that reasoning gap.

Core Workflow

1. Check whether a procedure requires prior authorization. 2. Pull relevant patient data from a FHIR R4 server. 3. Evaluate evidence against payer requirements using Claude. 4. Build a PA package with questionnaire responses, supporting documents, narrative, and likelihood score. 5. Route to clinician approval. 6. If denied, search for additional evidence and draft an appeal letter.

Architecture

flowchart LR
  Judge[Judge / User] --> UI[Demo UI\nNext.js 14]
  UI -->|POST /api/workflow/start| API[Express REST API]
  UI <-->|SSE /events| Events[SSE Event Bus\nwith replay]
  Prompt[Prompt Opinion] -->|Streamable HTTP /mcp| MCP[MCP Server\nExpress + MCP SDK]
  Prompt -->|A2A discovery| Card[/.well-known/agent.json]
  API --> Workflow[PA Workflow Orchestrator]
  MCP --> Tools[4 MCP Tools]
  Workflow --> Tools
  Tools --> Coverage[Coverage Rules\n+ AI fallback]
  Tools --> FHIR[HAPI FHIR R4\nDocker :8080]
  Tools --> Claude[Claude API\nClinical reasoning]
  Tools --> Cache[In-memory result cache]
  Events --> UI
  Workflow --> Events

MCP Tools

| Tool | Purpose | Key output | |------|---------|------------| | check_coverage_requirements | Determines if PA is required and returns payer documentation requirements. Unknown codes use Claude-generated fallback requirements. | PA status, requirements, source (payer_rules or ai_inferred) | | gather_clinical_evidence | Queries FHIR resources and evaluates each requirement with AI. | Evidence items, confidence, gaps, reasoning chains | | assemble_pa_documentation | Builds the PA package and likelihood score. Unknown codes receive a generic questionnaire. | QuestionnaireResponse, narrative, documents, likelihood score | | draft_appeal | Searches for additional evidence and drafts an appeal letter. | Appeal letter, citations, next steps, updated score |

All tools accept SHARP-style FHIR context through HTTP headers:

X-FHIR-Server-URL: http://localhost:8080/fhir
X-FHIR-Access-Token: 
X-Patient-ID: patient-12345

Dual Track Alignment

| Feature | Track 1: MCP Superpower | Track 2: A2A Agent | |---------|--------------------------|---------------------| | Streamable HTTP /mcp endpoint | Yes | Yes | | Four discoverable MCP tools | Yes | Yes | | SHARP FHIR context headers | Yes | Yes | | Real-time SSE reasoning trace | Yes | Yes | | Full PA workflow orchestration | Yes | Yes | | A2A Agent Card discovery | N/A | Yes: /.well-known/agent.json | | Prompt Opinion registration path | Yes | Yes |

Demo Scenarios

The repository includes a curated FHIR transaction bundle for patient-12345, so reviewers do not need Synthea or random data generation.

| Scenario | Code | Expected path | |----------|------|---------------| | Total Knee Arthroplasty | 27447 | PA required, evidence gathering, PA package, approval gate | | Humira / Adalimumab | J0135 | PA required, biologic medication criteria | | MRI Knee without contrast | 73721 | PA not required, immediate workflow completion | | Unknown CPT/HCPCS | Any other code | AI-inferred coverage requirements, generic PA package |

Quick Start

Prerequisites

- Node.js 18+ - npm 9+ - Docker Desktop or Docker Engine - Anthropic API key for AI-powered evidence, narrative, and appeal steps

One-command local demo

npm install
cp .env.example .env
Add ANTHROPIC_API_KEY=sk-ant-... to .env or export it in your shell
npm run demo

npm run demo starts HAPI FHIR, waits for readiness, loads the curated demo patient, starts the MCP server, and launches the Next.js UI.

Local URLs:

| Service | URL | |---------|-----| | Demo UI | http://localhost:3000 | | MCP server health | http://localhost:3001/health | | MCP endpoint | http://localhost:3001/mcp | | A2A Agent Card | http://localhost:3001/.well-known/agent.json | | HAPI FHIR | http://localhost:8080/fhir |

Manual startup

npm install
docker compose up -d
npm run data:load-demo
npm run dev
npm run ui:dev

Hosted Railway Demo

Railway is the preferred hosted path for Prompt Opinion and DevPost. Host three services:

| Service | Purpose | |---------|---------| | priorauth-fhir | HAPI FHIR R4 demo server | | priorauth-mcp | MCP, REST API, SSE, and A2A Agent Card | | priorauth-ui | Next.js demo dashboard |

Prompt Opinion should point at the hosted MCP endpoint:

https://priorauth-mcp-production.up.railway.app/mcp

Hosted demo URLs:

| Service | URL | |---------|-----| | Demo UI | https://priorauth-ui-production.up.railway.app | | MCP health | https://priorauth-mcp-production.up.railway.app/health | | A2A Agent Card | https://priorauth-mcp-production.up.railway.app/.well-known/agent.json | | FHIR demo server | https://priorauth-fhir-production.up.railway.app/fhir |

Detailed deployment steps are in docs/railway-deployment.md. For the FHIR Railway service, set hapi.fhir.server_address to the public HTTPS /fhir URL so HAPI's Swagger UI does not generate browser-blocked http:// OpenAPI links.

Local Fallback With ngrok

After the MCP server is running locally:

brew install ngrok
ngrok config add-authtoken $NGROK_AUTHTOKEN
npm run tunnel

Use the HTTPS forwarding URL printed by ngrok:

| Prompt Opinion field | Value | |----------------------|-------| | Transport | Streamable HTTP | | MCP server URL | https:///mcp | | Agent Card | https:///.well-known/agent.json |

For stable A2A discovery metadata, restart the MCP server with:

AGENT_PUBLIC_URL=https:// npm run dev

Detailed registration steps are in docs/integration-guide.md.

Screenshots And Video

The demo recording script is in docs/demo-script.md. Capture final screenshots into docs/screenshots/ using the checklist in docs/screenshots/README.md.

Planned DevPost visual assets:

| Asset | Path | Purpose | |-------|------|---------| | Dashboard overview | docs/screenshots/dashboard-overview.png | Workflow tracker, patient summary, and connected MCP status | | Evidence panel | docs/screenshots/evidence-panel.png | Requirement-level clinical evidence and reasoning | | PA likelihood score | docs/screenshots/likelihood-score.png | Circular approval probability score | | Approval gate | docs/screenshots/approval-gate.png | Clinician-in-the-loop submission checkpoint | | Appeal draft | docs/screenshots/appeal-draft.png | Denial response with additional evidence and guideline citations |

Prompt Opinion verification steps for marketplace listing, A2A handoff, and SHARP FHIR header propagation are in docs/prompt-opinion-verification.md.

Testing

npm run typecheck --workspace=mcp-server
npm test --workspace=mcp-server
npm run build --workspace=demo-ui
bash -n scripts/demo.sh
bash -n scripts/tunnel.sh

Current test coverage includes payer rules, likelihood scoring, and appeal helper behavior. A full workflow integration test is tracked in issue #68.

Project Structure

AgentsAssembleHackathon/
├── data/
│   ├── demo-patient-bundle.json       # Curated FHIR R4 demo bundle
│   └── questionnaires/                # Procedure-specific FHIR questionnaires
├── demo-ui/                           # Next.js dashboard
│   └── src/
│       ├── app/                       # App router pages/layout
│       ├── components/                # Patient, evidence, PA package, appeal UI
│       ├── lib/                       # SSE, API, workflow state adapters
│       └── types/                     # UI data types
├── docs/
│   ├── architecture.md
│   ├── demo-script.md
│   ├── integration-guide.md
│   └── judge-alignment.md
├── mcp-server/
│   └── src/
│       ├── ai/                        # Claude prompts, reasoning, likelihood scoring
│       ├── fhir/                      # FHIR client and resource types
│       ├── payer/                     # Coverage rules and questionnaires
│       ├── tools/                     # MCP tool implementations
│       ├── events.ts                  # SSE event bus with reconnect replay
│       ├── server.ts                  # Express, REST API, MCP transport, Agent Card
│       └── workflow.ts                # End-to-end PA workflow orchestration
├── scripts/
│   ├── demo.sh                        # One-command local demo
│   ├── load-demo-data.sh              # Curated FHIR data loader
│   └── tunnel.sh                      # ngrok tunnel helper
└── docker-compose.yml                 # HAPI FHIR server

Tech Stack

| Layer | Technology | |-------|------------| | MCP server | Express, TypeScript, @modelcontextprotocol/sdk | | Workflow API | REST endpoints plus Server-Sent Events | | AI reasoning | Claude via @anthropic-ai/sdk | | FHIR | HAPI FHIR R4 in Docker, raw typed fetch client | | UI | Next.js 14, React 18, Tailwind CSS, Framer Motion | | Data | Curated FHIR R4 transaction bundle | | Platform | Prompt Opinion via Streamable HTTP and A2A Agent Card |

Impact

| Metric | Manual process | PriorAuth Agent | |--------|----------------|-----------------| | PA assembly | Days to weeks | Under 60 seconds in demo | | Evidence review | Manual chart search | AI-assisted FHIR evidence evaluation | | Completeness | Staff-dependent | Systematic checklist and gap detection | | Appeal drafting | Re-review plus manual letter | Additional evidence search plus drafted appeal | | Auditability | Sparse notes | Structured reasoning chains and event trace |

License

MIT

---

Built for the Agents Assemble hackathon.