Healthcare AI Superpower — MCP Server

Prompt Opinion · Agents Assemble Hackathon Clinical decision-support tools for any AI agent, powered by FHIR R4 and the Model Context Protocol.

---

What This Does

AI agents on the Prompt Opinion platform can call this MCP server to reason over live FHIR patient data without ever handling EHR credentials directly. The platform bridges the SMART on FHIR session into the server via the ai.promptopinion/fhir-context extension — the agent just asks a question, and this server handles the rest.

Five clinical tools, one endpoint:

Tool	Clinical Use Case
fhir_query	Raw FHIR R4 resource retrieval (any resource type)
medication_review	Drug interactions · Beers Criteria · duplicate therapy · missing safety labs
summarize_clinical_notes	Structured extraction from FHIR DocumentReference notes
schedule_appointment	List, create, or cancel FHIR Appointment resources
identify_care_gaps	HEDIS · CMS · USPSTF quality gap identification

---

Live Endpoints

	URL
MCP Server	https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/mcp
Tools Listing	https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/mcp/tools
Health Check	https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/healthz
Demo Dashboard	https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/

---

Architecture

Prompt Opinion Platform
        │
        │  initialize → detects ai.promptopinion/fhir-context extension
        │  tool/call  → injects X-FHIR-Server-URL, X-FHIR-Access-Token, X-Patient-ID
        ▼
┌─────────────────────────────────────────┐
│         Express API Server              │
│         POST /api/mcp                   │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │   MCP Streamable HTTP Transport │   │
│   │   (JSON-RPC 2.0 · 2024-11-05)   │   │
│   └────────────────┬────────────────┘   │
│                    │                    │
│   ┌────────────────▼────────────────┐   │
│   │        MCP Tool Router          │   │
│   │  fhir_query                     │   │
│   │  medication_review              │   │
│   │  summarize_clinical_notes       │   │
│   │  schedule_appointment           │   │
│   │  identify_care_gaps             │   │
│   └────────────────┬────────────────┘   │
│                    │                    │
│   ┌────────────────▼────────────────┐   │
│   │         FHIR Client             │   │
│   │  Real (Bearer token) ──► EHR    │   │
│   │  Mock (no token)    ──► Demo    │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

---

Adding to Prompt Opinion

1. Go to Configuration → MCP Servers in your Prompt Opinion workspace.
2. Paste the MCP Server URL and click Continue. The platform sends an initialize request and reads the server's capabilities.
3. A FHIR Context toggle appears — enable it.
4. Review and authorize the SMART scopes your tools need.
5. Done. Every subsequent tool call will carry live FHIR credentials in the headers.

---

Prompt Opinion FHIR Extension

The server advertises support in every initialize response:

{
  "capabilities": {
    "extensions": {
      "ai.promptopinion/fhir-context": {
        "scopes": [
          { "name": "patient/Patient.rs",           "required": true  },
          { "name": "patient/MedicationRequest.rs", "required": false },
          { "name": "patient/Condition.rs",         "required": false },
          { "name": "patient/Observation.rs",       "required": false },
          { "name": "patient/DocumentReference.rs", "required": false },
          { "name": "patient/Appointment.crus",     "required": false }
        ]
      }
    }
  }
}

Once authorized, Prompt Opinion injects these headers on every tool call:

Header	Description
X-FHIR-Server-URL	FHIR server base URL — always present
X-FHIR-Access-Token	OAuth2 bearer token — present when EHR requires auth
X-Patient-ID	Active patient's FHIR ID — absent means system-level context
X-FHIR-Refresh-Token	Refresh token — only if offline_access scope granted
X-FHIR-Refresh-Url	Token refresh endpoint — only if offline_access scope granted

When FHIR headers are absent the server falls back to built-in demo data, so tools always return a useful response.

---

Tool Reference

fhir_query

Raw FHIR R4 resource query for a patient.

{
  "resourceType": "MedicationRequest",
  "patientId": "patient-001",
  "params": { "status": "active" }
}

Supported: Patient · MedicationRequest · Condition · Observation · DocumentReference · Appointment

---

medication_review

Comprehensive medication safety analysis.

• Drug-drug interaction detection (severity: HIGH / MODERATE / LOW)
• High-risk medications via Beers Criteria
• Duplicate therapeutic class detection
• Missing safety lab flags (e.g. INR monitoring for Warfarin)
• Prioritized clinical recommendations

{
  "patientId": "patient-001",
  "includeInactive": false
}

Example finding: Mary Johnson — HIGH Warfarin + Aspirin → increased bleeding risk, monitor INR closely.

---

summarize_clinical_notes

Retrieve and structure FHIR DocumentReference clinical notes.

Extracts: vitals · labs · active diagnoses · current medications · care plan · follow-up items

{
  "patientId": "patient-002",
  "noteType": "progress",
  "maxNotes": 5
}

---

schedule_appointment

Manage FHIR Appointment resources.

{
  "action": "create",
  "patientId": "patient-001",
  "newAppointment": {
    "startDateTime": "2026-06-01T10:00:00",
    "durationMinutes": 30,
    "serviceType": "Primary Care",
    "appointmentType": "FOLLOWUP",
    "providerName": "Dr. Sarah Mitchell",
    "reason": "Diabetes management follow-up"
  }
}

Actions: list · create · cancel

---

identify_care_gaps

Open quality gap identification aligned with HEDIS, CMS, and USPSTF guidelines.

{
  "patientId": "patient-001",
  "categories": ["all"]
}

Categories: preventive · chronic_disease · medications · behavioral_health · all

Example output (Mary Johnson): 11 open gaps including overdue HbA1c, missing annual diabetic eye exam, no flu vaccine on record, Warfarin without recent INR documentation.

---

Demo Patients

Built-in mock data is available at all times without a FHIR server.

Patient ID	Name	Profile	Clinical Highlight
patient-001	Mary Johnson	68F · DM2, HTN, AFib	HIGH Warfarin + Aspirin interaction · 11 care gaps
patient-002	Robert Chen	52M · DM2, HTN	HbA1c 9.2% (poorly controlled) · overdue labs
patient-003	Sandra Williams	40F · Depression, Chronic Pain	HIGH Sertraline + Tramadol serotonin syndrome risk

---

Quick Test (curl)

# 1. Verify the server is up
curl https://<domain>/api/healthz

# 2. Initialize and confirm the Prompt Opinion extension is declared
curl -X POST https://<domain>/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

# 3. Run the medication review tool (uses mock data — no FHIR token needed)
curl -X POST https://<domain>/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Patient-ID: patient-003" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "medication_review",
      "arguments": { "patientId": "patient-003" }
    }
  }'

---

Project Structure

artifacts/
├── api-server/                       # MCP server (Node 24 · Express 5 · esbuild)
│   └── src/
│       ├── mcp/
│       │   ├── server.ts             # Factory + Prompt Opinion extension declaration
│       │   ├── fhir/
│       │   │   ├── client.ts         # FHIR HTTP client with mock fallback
│       │   │   └── mock-data.ts      # Realistic FHIR R4 demo data
│       │   └── tools/
│       │       ├── fhir-query.ts
│       │       ├── medication-review.ts
│       │       ├── clinical-notes.ts
│       │       ├── appointments.ts
│       │       └── care-gaps.ts
│       └── routes/
│           ├── mcp.ts                # Streamable HTTP transport + FHIR header extraction
│           └── health.ts
│
└── healthcare-demo/                  # Interactive demo dashboard (React 19 · Vite 7)
    └── src/
        ├── pages/Dashboard.tsx       # Patient selector + live tool runner
        ├── lib/mcp-client.ts         # MCP JSON-RPC client
        ├── App.tsx
        └── index.css                 # Clinical teal/navy theme

---

Local Development

Requirements: Node.js 24 · pnpm 10+

# Install all workspace dependencies
pnpm install

# Run the MCP API server (proxied to /api by the Replit reverse proxy)
pnpm --filter @workspace/api-server run dev

# Run the demo dashboard (proxied to /)
pnpm --filter @workspace/healthcare-demo run dev

# Full TypeScript check across all packages
pnpm run typecheck

---

Stack

Layer	Technology
Runtime	Node.js 24
Language	TypeScript 5.9
MCP SDK	@modelcontextprotocol/sdk 1.29
Transport	Streamable HTTP (MCP 2024-11-05)
API framework	Express 5
Build	esbuild
Frontend	React 19 · Vite 7 · Tailwind CSS 4
Monorepo	pnpm workspaces

---

Hackathon

Built for the Prompt Opinion Agents Assemble Challenge — a $25,000 prize pool competition focused on MCP, A2A, and FHIR interoperability in healthcare AI.

• Platform: app.promptopinion.ai
• Docs: docs.promptopinion.ai
• Challenge: Agents Assemble
• Discord: discord.gg/cCBxKpdS7j