H.E.R.O. — Health Entity Rendering Orchestrator

HERO is an intelligent A2A orchestrator that automates complex clinical workflows. It securely routes patient FHIR data to specialized MCP tools to generate instant, actionable insights.

Comment

Inspiration

Healthcare interoperability remains one of the most critical unsolved problems in modern medicine. Every day, clinicians waste hours navigating fragmented Electronic Health Record (EHR) systems, manually cross-referencing patient data buried in deeply nested FHIR JSON bundles. A single patient's record can contain hundreds of Observation, Condition, and Medication resources — each encoded with LOINC, SNOMED CT, and ICD-10 standards that require specialized knowledge to interpret.

We asked ourselves: What if an AI agent could do this instantly?

The vision was clear — build an intelligent orchestrator that bridges the gap between raw FHIR data and actionable clinical insights, using the emerging MCP and A2A protocols to create a truly interoperable healthcare AI system.

What it does

H.E.R.O. (Health Entity Rendering Orchestrator) is an AI-powered clinical intelligence system composed of two core layers:

Layer Component Role
Layer A FHIR MCP Server Exposes standardized tools for querying patient vitals and conditions over the Model Context Protocol
Layer B HERO A2A Agent Orchestrates tool calls, performs clinical analysis, maps conditions to body systems, and flags risks

The MCP Server provides two specialized FHIR parsing tools:

  • patient_vitals_tool — Parses FHIR R4 Observation bundles and extracts Heart Rate (LOINC 8867-4), Blood Pressure (LOINC 8480-6, 8462-4), and SpO2 (LOINC 2708-6). Returns clean, normalized values.
  • patient_conditions_tool — Filters FHIR R4 Condition bundles for active diagnoses only (clinicalStatus.coding[0].code === "active") and returns human-readable condition names from SNOMED/ICD-10 coded entries.

The HERO Agent consumes these outputs and produces structured clinical intelligence — mapping each condition to its anatomical body system, flagging abnormal vitals, identifying cross-condition risk patterns, and generating evidence-based follow-up recommendations.

Security is enforced via the SHARP (Secure Healthcare Agent Request Protocol) specification, ensuring patient IDs and FHIR tokens propagate securely through the entire agent call chain without custom token vaults.

How we built it

The system architecture follows a clean two-layer design, built entirely in Python:

Layer A — MCP Server:

# Core stack
Python + Starlette + Uvicorn + MCP SDK
# Transport: HTTP/SSE
GET  /sse        → Event stream (client connects here)
POST /messages/  → JSON-RPC (client sends tool calls here)
GET  /           → Health check endpoint

The server uses the low-level mcp.server.Server class with explicit SseServerTransport configuration. Tools are registered via @app.list_tools() and @app.call_tool() decorators, returning proper mcp.types.Tool pydantic models. DNS rebinding protection is disabled via TransportSecuritySettings to support external tunnel exposure through ngrok.

Layer B — A2A Agent: Built on Google ADK Agent-to-Agent architecture patterns. The orchestrator agent receives parsed FHIR data, applies clinical logic (condition-to-anatomy mapping), and broadcasts consolidated state via WebSocket.

Platform Integration: The MCP Server is registered on the Prompt Opinion platform via its SSE transport endpoint. The HERO agent is configured with a custom system prompt that instructs it to always invoke both MCP tools and deliver structured clinical analysis.

Technology Purpose
Python 3.13 Core runtime
MCP SDK Model Context Protocol implementation
Starlette + Uvicorn ASGI web framework + server
Google ADK A2A agent orchestration patterns
WebSockets Real-time state broadcasting
ngrok HTTPS tunnel for platform connectivity
Prompt Opinion Agent + MCP registration platform
HL7 FHIR R4 Healthcare data standard
LOINC / SNOMED CT / ICD-10 Clinical coding systems

Challenges we ran into

Building at the intersection of healthcare standards and emerging AI protocols presented several significant challenges:

1. MCP Transport Security vs. External Tunneling The MCP SDK's SseServerTransport includes an internal DNS rebinding protection middleware that silently drops requests from external tunnels like ngrok. The error — ValueError: Request validation failed — gave no indication of the cause. We had to trace through the library source code to discover and override TransportSecuritySettings.

2. Starlette Routing Conflicts The sse.handle_post_message is a raw ASGI application that manages its own HTTP responses. Wrapping it in a Starlette Route caused double-response crashes (RuntimeError: Unexpected ASGI message). Using Mount without trailing slashes caused 307 redirects. The solution required precise alignment — trailing slashes on both SseServerTransport("/messages/") and Mount("/messages/").

3. MCP Type System Enforcement The list_tools handler must return mcp.types.Tool pydantic model instances, not raw Python dictionaries. The error — 'dict' object has no attribute 'name' — only surfaced during live client connections, not at startup.

4. FHIR Data Complexity FHIR bundles are deeply nested. A single vital sign observation requires traversing entry[].resource.code.coding[].code for LOINC matching, then extracting from valueQuantity.value and valueQuantity.unit. Robust error handling was essential for every level of nesting.

Accomplishments that we're proud of

  • End-to-end MCP compliance — Our server passes full handshake, initialization, tool listing, and tool invocation tests using the official MCP client SDK, both locally and through external HTTPS tunnels
  • Zero-dependency FHIR parsing — No heavy FHIR libraries required; our tools parse raw bundle JSON with precision targeting of LOINC and SNOMED codes
  • SHARP specification implementation — Secure token propagation without custom vaults, following the platform's native security model
  • Production-grade SSE transport — Health check endpoint, proper ASGI routing, and tunnel-compatible security configuration
  • Successful Prompt Opinion integration — Both MCP tools discovered and callable from the platform's agent interface
  • Professional demo data — Complete clinical discharge summary PDF with realistic vitals, lab results, spirometry, and ICD-10 coded diagnoses

What we learned

  • The MCP protocol is powerful but unforgiving — transport configuration, type systems, and routing must be exact
  • Healthcare data standards (FHIR, LOINC, SNOMED) have steep learning curves but provide incredible interoperability once mastered
  • The A2A pattern enables clean separation between data retrieval (MCP tools) and clinical reasoning (agent logic)
  • SHARP specification elegantly solves the credential propagation problem in multi-agent healthcare systems
  • Building for hackathon platforms requires understanding their specific discovery and connectivity patterns

What's next for H.E.R.O. — Health Entity Rendering Orchestrator

Phase Enhancement Impact
Phase 1 Add patient_medications_tool and patient_allergies_tool to the MCP server Complete medication reconciliation and drug-allergy interaction detection
Phase 2 Integrate clinical decision support rules (CDS Hooks) Automated alerts for dangerous drug interactions and contraindicated prescriptions
Phase 3 Multi-patient cohort analysis Enable population health monitoring across patient groups
Phase 4 SMART on FHIR OAuth2 authentication Replace SHARP simulation with production-grade EHR authentication
Phase 5 3D Clinical Digital Twin visualization Interactive anatomical body model where conditions illuminate affected organ systems in real time

The long-term vision is a fully autonomous clinical intelligence system where AI agents continuously monitor patient records, surface critical insights, and alert care teams — turning reactive healthcare into proactive medicine.

Built With

  • google-adk-(agent-to-agent)
  • hl7-fhir-r4
  • icd-10
  • loinc
  • model-context-protocol-(mcp)-sdk
  • ngrok
  • prompt-opinion-platform
  • python
  • sharp-specification
  • snomed-ct
  • starlette
  • uvicorn
  • websockets
Share this project:

Updates