FHIRBridge

FHIRBridge - About the Project (Devpost Submission)

Inspiration

Healthcare AI has a "last mile problem". While large language models can reason about clinical scenarios, they lack access to the actual patient data needed to be useful. Every healthcare AI developer faces the same challenge: building custom integrations to Electronic Health Record (EHR) systems.

Looking at the current landscape, I saw dozens of specialized healthcare agents being built (prior authorization, clinical trial matching, medication safety), but every single one was rebuilding the same FHIR integration from scratch. This is inefficient and slows innovation.

The FHIR (Fast Healthcare Interoperability Resources) standard was designed to solve interoperability—but FHIR APIs are notoriously complex. A single patient medication list can return 500+ lines of nested JSON. Parsing references, handling pagination, managing OAuth tokens, and dealing with vendor-specific quirks means weeks of development work for each new agent.

I realized that if we want an ecosystem of healthcare AI agents, we need a shared infrastructure layer. Instead of every developer building their own FHIR integration, what if we had a production-ready MCP server that any agent could use?

FHIRBridge is not another specialized clinical app—it's the data access layer that all healthcare agents can build on. Just like PostgreSQL for databases or Stripe for payments, FHIRBridge provides the infrastructure so developers can focus on clinical workflows, not data plumbing.

That's how FHIRBridge was born.

What It Does

FHIRBridge is a Model Context Protocol (MCP) server that exposes 11 production-ready tools for accessing FHIR R4 patient data—the most comprehensive FHIR toolkit in the Agents Assemble hackathon:

Patient Information

get_patient_demographics - Basic patient info (name, DOB, gender, contact, identifiers)
search_patients - Search by demographics (name, DOB, identifier, gender)

Clinical Data

get_patient_conditions - Diagnoses with ICD-10 codes
get_medication_list - Medications with dosing and frequency
get_lab_results - Lab results with LOINC codes and reference ranges
get_allergies - Allergies and intolerances
get_vital_signs - BP, HR, temperature, respiratory rate, O2 saturation, BMI

Care History

get_encounters - Visit/encounter history
get_procedures - Procedure history with CPT codes

Analysis

get_comprehensive_summary - Complete patient summary combining all data sources
check_drug_interactions - Real-time drug-drug interaction checking via NLM RxNav API

All tools implement the SHARP Extension Specs, automatically handling healthcare context (patient_id, fhir_server_url, fhir_access_token) so agents can focus on clinical logic rather than infrastructure.

Why This Matters

Unlike specialized MCP servers built for one clinical use case, FHIRBridge is reusable infrastructure. Want to build a prior authorization agent? Use FHIRBridge. Clinical trial matcher? Use FHIRBridge. Medication safety checker? Use FHIRBridge.

Proven in production: I built MedSync, a medication reconciliation agent, in 2 days using FHIRBridge. It successfully detected life-threatening drug contraindications that could have killed the demo patient. Without FHIRBridge, that integration alone would have taken 2 weeks.

How I Built It

Architecture

┌─────────────────┐
│   AI Agent      │ (Any agent on Prompt Opinion)
└────────┬────────┘
         │ MCP JSON-RPC 2.0
         │
┌────────▼────────┐
│  FHIRBridge     │ (Python MCP Server)
│  - 11 Tools     │
│  - SHARP Ctx    │
│  - Parsers      │
└────────┬────────┘
         │ FHIR R4 REST API
         │
┌────────▼────────┐
│  FHIR Server    │ (HAPI, Epic, Cerner, etc.)
│  - Patient data │
│  - OAuth2 auth  │
└─────────────────┘

Technology Stack

Python 3.12 - Core language
MCP SDK (v1.26.0) - Model Context Protocol implementation
Starlette + Uvicorn - HTTP server framework (JSON-RPC over HTTP)
httpx - Async HTTP client for FHIR API calls
Pydantic - Data validation and settings management

Key Components

1. FHIR Client (src/fhir/client.py)

async with FHIRClient(base_url=fhir_server_url,
                      access_token=token) as client:
    patient = await client.get_resource("Patient", patient_id)

Handles OAuth2 authentication, error handling (404, 401, 403, 5xx), and network resilience.

2. Resource Parsers (src/fhir/parsers.py)

The most critical piece. FHIR JSON is extremely verbose:

// FHIR raw output (500+ lines)
{
  "resourceType": "Bundle",
  "entry": [{
    "resource": {
      "resourceType": "MedicationRequest",
      "medicationCodeableConcept": {
        "coding": [{
          "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
          "code": "206765",
          "display": "Lisinopril 10 MG Oral Tablet"
        }]
      },
      "dosageInstruction": [{
        "timing": {
          "repeat": {
            "frequency": 1,
            "period": 1,
            "periodUnit": "d"
          }
        }
      }]
      // ... 20+ more nested fields
    }
  }]
}

FHIRBridge parses this into clean, LLM-friendly JSON:

{
  "success": true,
  "count": 1,
  "medications": [{
    "medication_name": "Lisinopril 10 MG Oral Tablet",
    "rxnorm_code": "206765",
    "dosage": "1 tablet daily",
    "status": "active"
  }]
}

This 95% reduction in verbosity makes it practical for AI agents to process medication lists without hitting token limits.

3. SHARP Context Handler (src/sharp/context.py)

Extracts and validates healthcare context from every tool call:

context = extract_sharp_context(arguments)
# Returns: {patient_id, fhir_server_url, fhir_access_token}

This enables multi-tenancy and security—each tool call operates on the patient/server specified by the calling agent.

4. Pagination Handler (src/fhir/pagination.py)

FHIR search results return "Bundles" with pagination links. FHIRBridge automatically follows Bundle.link[relation="next"] to retrieve all results, respecting safety limits.

5. HTTP Transport (src/http_server.py)

Initially, I built this for stdio transport (standard MCP). But Prompt Opinion uses JSON-RPC over HTTP, so I had to implement:

POST endpoint for JSON-RPC messages
GET endpoint for SSE (Server-Sent Events) streaming
Protocol negotiation (initialize, tools/list, tools/call)
Notification handling (notifications/initialized)

Challenges I Faced

1. FHIR Complexity

FHIR is a beast. A single Patient resource has 50+ optional fields. A MedicationRequest can represent medications in 6 different ways (medicationCodeableConcept, medicationReference, etc.). References are URLs that need to be resolved. Extensions are everywhere.

Solution: I built custom parsers for each resource type, handling all the edge cases. For example, the medication parser checks both medicationCodeableConcept and medicationReference, resolves the reference if needed, extracts the first matching coding from the preferred code system (RxNorm > SNOMED > text), and formats dosing instructions into human-readable strings.

2. MCP HTTP Transport Documentation

The MCP SDK documentation focuses heavily on stdio transport (pipes). HTTP transport documentation is sparse. I had to:

Reverse-engineer the JSON-RPC message format from Prompt Opinion's requests
Figure out that POST and GET endpoints serve different purposes
Handle notifications (which have no id field and expect no response)
Implement SSE streaming for real-time communication

Solution: I captured Prompt Opinion's actual requests in the server logs and built the protocol handler by example. Trial and error, but it worked.

3. SHARP Context Propagation

For security and multi-tenancy, every tool call needs to know:

Which patient? (patient_id)
Which FHIR server? (fhir_server_url)
Authentication? (fhir_access_token)

SHARP Extension Specs define how to pass this context, but implementing it correctly required:

Extracting context from tool arguments (optional parameters)
Validating that required fields are present
Defaulting to environment variables for testing
Passing context through to the FHIR client

Solution: Created a dedicated extract_sharp_context() function that every tool calls first. This centralizes validation and provides good error messages.

4. Bundle Pagination

FHIR search results are paginated. A patient might have 100 lab results, but the server returns 20 at a time with a next link. If you don't follow the links, you get incomplete data.

Solution: Built an async pagination handler that follows next links recursively, with a safety limit (max 10 pages) to prevent infinite loops.

5. Testing with Real FHIR Servers

I needed a FHIR server to test against. Options:

Local HAPI FHIR server - Complex setup
Epic/Cerner sandbox - Requires OAuth dance, vendor-specific quirks
Public HAPI server - Perfect for testing, but data is ephemeral

Solution: Used the public HAPI FHIR test server (https://hapi.fhir.org/baseR4). I created a demo patient (Maria Santos) with realistic clinical data and planted medication safety issues to test with MedSync.

6. Drug Interaction Checking

I wanted real drug interaction data, not just mock responses. The NLM provides a free RxNav API, but:

Takes medication names OR RxNorm codes (not both)
Returns different JSON structures depending on the input
Rate limits apply
Requires fuzzy matching (users might say "Aspirin" or "ASA" or "Acetylsalicylic Acid")

Solution: Built a two-phase approach:

Resolve medication names to RxNorm RxCUIs using /approximateTerm endpoint
Call /interaction/list with resolved RxCUIs
Parse the interaction severity and descriptions

What I Learned

Technical Lessons

Standards compliance matters: By strictly following FHIR R4 and SHARP specs, FHIRBridge works with any compliant server (HAPI, Epic, Cerner). No vendor lock-in.
Abstraction is worth the effort: Those parsers were painful to write, but they're the key value-add. Reducing 500 lines of FHIR JSON to 20 lines of clean data makes the difference between "unusable" and "production-ready."
Async Python scales: Using async/await throughout means FHIRBridge can handle multiple concurrent agent requests without blocking. For a healthcare application serving multiple agents, this is critical.
Error handling is half the code: Network failures, 404s, malformed FHIR responses, missing fields—robust error handling is what separates a demo from a product.

Healthcare AI Lessons

Context is everything: In healthcare, you can't just call get_medications(). You need to know which patient, which server, with what permissions. SHARP context handling is essential.
Data quality varies wildly: Some FHIR servers have perfect data. Others have missing codes, empty fields, or inconsistent formatting. Parsers need to be defensive.
Medication reconciliation is AI-perfect: It requires cross-referencing multiple data sources (meds, conditions, encounters, allergies) under time pressure. Perfect use case for LLMs with tool access.

Prompt Opinion Platform Lessons

HTTP transport is production-grade: Unlike stdio (which requires process management), HTTP transport makes MCP servers easy to deploy, monitor, and scale.
Marketplace is key: Publishing to the Marketplace makes tools discoverable. Instead of every agent developer finding and configuring FHIRBridge, they just add it from the Marketplace.
Video demos matter: Judges won't have time to deeply explore every project. A 3-minute video that shows the value proposition is critical.

What's Next for FHIRBridge

Short-term (Next 3 months)

Add more FHIR resources: Immunizations, CarePlans, DiagnosticReports, DocumentReferences
Performance optimization: Redis caching layer for frequently-accessed patients
Monitoring: OpenTelemetry integration for observability
Write operations: Currently read-only; add create/update tools for care planning

Medium-term (6-12 months)

FHIR R5 support: Latest FHIR version with improved data models
Epic/Cerner optimizations: Vendor-specific extensions for better compatibility
Bulk data export: FHIR $export operation for population health use cases
SMART App Launch: Simpler OAuth flow for EHR integration

Long-term Vision

FHIRBridge as Healthcare AI Infrastructure: Every healthcare AI agent uses FHIRBridge for data access, just like every web app uses PostgreSQL for databases
Open source ecosystem: Community-contributed tools for specialized use cases
Enterprise offering: Hosted FHIRBridge-as-a-Service for healthcare AI companies
Multi-standard support: Expand beyond FHIR to HL7 v2, X12, CDA

Impact Potential

If FHIRBridge becomes the standard data access layer for healthcare AI:

Development time: $ \text{Weeks} \rightarrow \text{Minutes} $ to integrate EHR data
Cost savings: No duplicated integration work across projects
Innovation velocity: Developers focus on clinical workflows, not FHIR parsing
Interoperability: All agents speak the same data language
Quality: Centralized, battle-tested parsers vs. everyone rolling their own

Example: Medication Reconciliation at Scale

With FHIRBridge, I built MedSync (a medication reconciliation agent) in 2 days. Without FHIRBridge, it would have taken 2 weeks just to build the FHIR integration.

If we extrapolate this across the healthcare AI ecosystem:

$$ \text{Time Saved} = N_{\text{agents}} \times (T_{\text{without}} - T_{\text{with}}) $$

Where:

$ N_{\text{agents}} $ = Number of healthcare AI agents built
$ T_{\text{without}} $ = Time to build custom FHIR integration (2 weeks)
$ T_{\text{with}} $ = Time to integrate FHIRBridge (1 hour)

For just 100 healthcare AI projects, FHIRBridge saves:

$$ 100 \times (2 \text{ weeks} - 1 \text{ hour}) \approx 200 \text{ weeks} = 3.8 \text{ developer-years} $$

That's $500,000+ in saved development costs (at $130k avg developer salary).

Try It Yourself

GitHub: github.com/jamador47/FhirBridge/
Prompt Opinion Marketplace: Search for "FHIRBridge"
Demo Patient: maria-santos on HAPI FHIR test server
Documentation: See README.md for setup instructions

How FHIRBridge Compares

During the hackathon, I reviewed other FHIR-based MCP servers to understand the landscape:

Server	Tools	Focus	Positioning
FHIRBridge	11	General-purpose infrastructure	Platform for any healthcare agent
FHIR Healthcare Tools	7	Clinical calculations + data access	Similar but less complete
Clinical Decision Support	9	CDS + risk scoring	Specialized for decision support
ClinicalMem	9	Persistent memory + conflict detection	Specialized for safety monitoring
AuthArmor, AuthPilot, ALICE	3-7	Prior authorization only	Single-use-case agents
TrialBridge	7	Clinical trial matching only	Single-use-case agent

FHIRBridge's unique advantages:

Most comprehensive (tied for most tools)
Only one positioned as reusable infrastructure vs. specialized application
Production-ready parsers (95% verbosity reduction)
Real external API integration (NLM RxNav)
Proven with working demo agent (MedSync) showing it works end-to-end

The vision difference: Other servers solve specific clinical problems. FHIRBridge solves the infrastructure problem so developers can solve any clinical problem.

Acknowledgments

HAPI FHIR Project: For providing the public test server
Anthropic: For the MCP SDK and documentation
NLM RxNav Team: For the free drug interaction API
HL7/FHIR Community: For creating the standard that makes this possible
Prompt Opinion: For organizing this hackathon and building the platform

Built With

fhir
httpx
mcp-sdk
pydantic
python
starlette
uvicorn