fhir-journey-mcp

A read-only MCP server that gives an AI agent a patient's context from any FHIR R4 server: who they are, when they were last seen, what is booked next, and which discharged patients never got a follow-up.

Hospitals already run HIS, EMR and scheduling systems that speak (some) FHIR. An agent that calls patients or answers the front desk needs that context before it says a word, and it should not need write access to get it.

Tools

fhir_find_followups_due output, from the live smoke run below:

[
  { "patient": "Meera Demo", "discharged": "2026-10-09T12:00:00.000Z", "dueBy": "2026-10-16T12:00:00.000Z", "lateBooking": "2026-10-28T10:00:00.000Z" },
  { "patient": "Rohan Demo", "discharged": "2026-10-13T12:00:00.000Z", "dueBy": "2026-10-20T12:00:00.000Z", "lateBooking": null }
]

Related MCP server: LangCare MCP FHIR Server

Run it

npm install
npm run build
FHIR_BASE_URL=https://your-server/fhir FHIR_TOKEN=... npx fhir-journey-mcp

Claude Desktop / any MCP client:

{
  "mcpServers": {
    "fhir-journey": {
      "command": "node",
      "args": ["/path/to/fhir-journey-mcp/dist/mcp/server.js"],
      "env": { "FHIR_BASE_URL": "https://hapi.fhir.org/baseR4" }
    }
  }
}

With no FHIR_BASE_URL it uses the public HAPI test server, which holds synthetic data only.

Verify it

npm test          # 22 offline tests against a fake FHIR server
npm run seed      # loads 4 synthetic patients with known answers, tagged per run
npm run smoke     # starts the server over stdio and checks every tool's answer

scripts/seed.ts documents the expected answers (who is booked, who is due, whose follow-up was cancelled and rebooked late). npm run smoke passes 10/10 against the public HAPI server.

Design choices

• Read-only. Booking, cancelling and messaging patients belong behind a human or a separate, audited tool.

• No full-table reads. Search tools refuse to run without a filter.

• Ids are validated before they reach a URL path; a model can't turn patientId into ../Practitioner/1.

• Paging links are only followed on the configured origin, so a bearer token is never sent to a host the server named in a next link.

• Search URLs are redacted from errors, since they carry names and phone numbers.

• GET retries on 408/429/5xx with backoff; transaction POSTs are never replayed.

• Compact summaries, not raw resources: less token spend, fewer fields for a model to misread.

• meta.tag filter on every search tool, for scoping to one tenant or one test dataset.

Not done / honest limits

• Tested against HAPI FHIR only. Real hospital systems use FHIR profiles and partial implementations differently (chained search and _sort support vary). Not tested against any production EMR/HIS.

• No ABDM gateway integration, consent artefact handling, or SMART-on-FHIR auth flow; it takes a bearer token you already have.

• "Follow-up" means any live appointment for the patient after discharge, not one matched to the same department or condition.

• fhir_find_followups_due makes one appointment query per patient (5 in parallel). Fine for a daily worklist, not for a 10,000-discharge backfill.

MIT licensed.