Referral Ready MCP`

Referral Ready MCP turns patient chart context into specialist-ready referrals inside Prompt Opinion by flagging missing workup, surfacing alarm findings, and exporting FHIR-native handoff artifacts.

Comment

Referral Ready MCP is a focused healthcare MCP server built for Prompt Opinion and the Agents Assemble hackathon. The project tackles one narrow but expensive workflow failure: referrals that reach a specialist with incomplete context, missing workup, or no clear handoff package.

What inspired me

I was inspired by the gap between what clinical AI usually demos and what real care teams actually need. Many healthcare demos stop at summarization, but referral coordination is a last-mile operational problem. A referral can fail even when all the relevant chart data exists, simply because the receiving specialist gets an incomplete packet, a missing lab, or a vague referral reason.

Prompt Opinion's healthcare-native workflow and patient-context-aware MCP support made this a strong problem to solve inside the platform instead of outside it. That made it possible to build something grounded in live patient context rather than another standalone chatbot.

What the project does

Referral Ready MCP turns patient context into specialist-ready referral outputs inside Prompt Opinion. For the current MVP, it supports gastroenterology and cardiology workflows and produces:

  • referral readiness analysis
  • missing-workup detection
  • evidence extraction from FHIR resources and notes
  • specialist-ready referral packet drafting
  • patient prep guidance
  • follow-up task generation
  • FHIR-native export as Task, DocumentReference, and Provenance

The readiness score is intentionally bounded so it stays operational and interpretable:

$$ 0 \leq \text{readinessScore} \leq 100 $$

How I built it

I built the project as a TypeScript monorepo with a narrow, production-oriented architecture:

  • a Cloudflare Worker exposes the MCP server over streamable HTTP
  • Prompt Opinion passes patient-context-aware FHIR headers into the MCP server
  • a deterministic referral engine handles readiness scoring, gap detection, and red-flag surfacing
  • Google-backed narrative generation is used only where language lift matters most, such as packet drafting and patient prep
  • a lightweight proof UI on Cloudflare Pages provides a stable public surface for judges
  • synthetic FHIR R4 bundles provide deterministic rehearsal cases for the demo path

A key design decision was to keep the logic narrow and structured. Instead of trying to answer every clinical question, the MCP server focuses on a small tool surface that maps directly to a real coordination workflow.

Challenges I faced

The hardest part was not writing the referral logic itself. The hardest part was making the workflow reliable inside a real agent platform.

The main challenges were:

  • integrating with Prompt Opinion's FHIR-context MCP extension exactly as expected
  • handling model demand and free-tier token limits during multi-step agent runs
  • keeping tool responses rich enough to be useful, but compact enough not to blow up the downstream model context
  • preserving deterministic, auditable outputs while still using generation where it actually improved the handoff quality

One important engineering lesson was that MCP response design matters as much as the model choice. I had to compact tool outputs carefully so the agent could complete readiness, packet drafting, patient prep, tasks, and export in a single workflow without running into request-size failures.

What I learned

I learned three big things while building this project:

  1. In healthcare workflows, narrow operational AI is usually more valuable than broad conversational AI.
  2. Interoperability matters most when the workflow ends in artifacts that another system or human can actually use.
  3. For agent systems, the structure and size of tool outputs can determine whether a workflow is reliable in practice.

I also learned that a strong hackathon project in this space does not need to solve every healthcare problem. It needs to solve one painful workflow clearly, reliably, and in a way that judges can understand quickly.

Why this project matters

Referral Ready MCP is designed around a simple idea: the referral should not fail because the chart handoff was sloppy. By identifying missing workup before the specialist visit is wasted, and by producing interoperable outputs instead of generic summaries, the project targets a real last-mile coordination problem with a practical implementation.

Built With

Share this project:

Updates