This guide describes the reference implementation at its stated update date. Keep the documented support boundary in view as you evaluate or extend it.

The published package path is the README start: npx -y @lastehr/mcp init, then this repository's local HAPI stack. That release's no-account backend is FHIR_BACKEND=hapi with FHIR_BASE_URL or HAPI_BASE_URL. Local-lab failures are in Troubleshooting the local lab.

The hosted demo is a separate browser walkthrough:

https://www.lastehr.com/demo

It uses synthetic patients, needs no account, and every write stops at an approval card.

Recorded approval and cancellation

Watch the 90-second walkthrough or view it on the homepage.

This is an edited, sampled screen recording of the fixed local synthetic walkthrough, captured November 6, 2026, from clean source fb24732 (@lastehr/mcp@0.5.1, published on npm; git tag mcp-v0.5.1). No external model is called. The browser frames are actual app captures; the adjoining pane shows separate paginated GET snapshots from its disposable local HAPI FHIR store.

TimeTranscript
0:00–0:08A fixed synthetic walkthrough. The browser approval and FHIR persistence paths are real.
0:08–0:22The 72 bpm proposal waits for a human decision. An independent read finds the original seven Observation IDs.
0:22–0:32Inspect the proposed patient reference, LOINC 8867-4, value 72 bpm, and UCUM /min in the FHIR preview.
0:32–0:36Approve and save. The pane keeps the last completed backend snapshot until the next read.
0:36–0:48The new FHIR read finds eight Observations: exactly one added ID. Its reviewed fields and AIAST label pass the checks.
0:48–1:00Submit again. Scripted mode repeats the same proposal; another read still finds the eight approved-state IDs.
1:00–1:04Cancel and revise the second proposal.
1:04–1:15Read FHIR again: the ID set is unchanged from after approval, with zero additional Observations.
1:15–1:30Try the pinned walkthrough. These checks cover persistence mechanics, not clinical correctness, model quality, or production authorization.

FHIR proof JSON · English captions · Capture method and limits. The baseline was read before submitting the first proposal and rechecked while its card was waiting. Both snapshots contained the same seven IDs. The video uses edited timing and holds captured frames for readability.

To reproduce the recorded app version, use a clean directory and the prerequisites below, check out fb2473246c5900ec8e714358dacb36a3167d4602, then run npm ci and npm run demo:local. Approve once, repeat and cancel, and compare all paginated Observation IDs directly in your local FHIR store. Resource IDs will differ between seeded stacks.

Zero-key local synthetic demo with HAPI FHIR

Use this path when you want to inspect the approval loop without a Medplum account or model-provider key.

Prerequisites:

  • Node 22.18+ (or 24.2+)
  • Docker

From a fresh checkout:

bash
git clone https://github.com/cbetz/last-ehr.git
cd last-ehr
npm install
npm run demo:local

The command starts HAPI FHIR and Postgres, waits for the server, resets and seeds the synthetic records, then starts the app at http://localhost:3000/demo. It forces the local HAPI + scripted settings for its child processes, so it needs neither .env.local nor an external model key. Your normal .env.local is not edited or used to select the backend or model for this command.

On the first run, Docker may need to pull images and HAPI can take a few minutes to initialize. Press Ctrl-C to stop Next.js; the local FHIR stack and its data stay available. When you want to remove them, run:

bash
npm run demo:local:down

This is a deterministic walkthrough, not an offline model bundle: it makes no model-provider request and does not interpret the prompt. It always searches the seeded Maria Garcia record, proposes a single Heart rate: 72 bpm Observation, and waits for approval. The server rejects scripted mode unless the opt-in flag, FHIR_BACKEND=hapi, and a local HAPI URL are all present; the wrapped FHIR backend rejects reads or writes outside that synthetic record and fixed observation.

The local HAPI server itself has no auth. Use it for local, single-tenant synthetic evaluation only. Re-run npm run seed if the scripted demo says its seeded patient is missing.

Inspect the read-only MCP tools

The checkout also includes a separate MCP Local Lab for evaluating the two chart-reading tools without FHIR/Medplum credentials or a provider API key:

bash
npm run mcp:demo -- --client claude-code

It prepares the same local HAPI stack and prints a client registration command. The MCP process is hard-wired to the local Docker endpoint and exposes only the four repository fixture patients through search_patients and show_patient_info. This is a synthetic evaluation path, not generic HAPI support or a substitute for the published @lastehr/mcp package. Claude Code or Cursor still uses its usual model account and may transmit those synthetic tool results to its provider. Port 8080 must be free; leave the local stack running while connected and use npm run demo:local:down when finished. See the MCP guide for Cursor/JSON configuration and the full boundary.

Use a real model instead

npm run demo:local is intentionally fixed to the safe walkthrough. To exercise the full agent instead, copy .env.example to .env.local, set FHIR_BACKEND=hapi, FHIR_BASE_URL=http://localhost:8080/fhir, NEXT_PUBLIC_QUICKSTART=true, and a supported provider configuration, for example:

bash
AI_PROVIDER=openai
OPENAI_API_KEY=...

Leave LASTEHR_SCRIPTED_DEMO and NEXT_PUBLIC_SCRIPTED_DEMO unset, then run the HAPI stack:

bash
docker compose up -d
npm run fhir:wait
npm run seed
npm run dev

Public NEXT_PUBLIC_* values are read at startup. The real agent can use its full tool surface (see FHIR coverage) and requires a tool-capable model credential.

To run the app itself in Docker too:

bash
npm run docker:local

This uses docker-compose.yml plus docker-compose.app.yml and reads the build-time public values from .env.local.

Separately, if you only want the scripted zero-key lab without a local build: release tags and manual publish runs push a prebuilt image whose scripted configuration is baked in at build time, so it always runs the scripted walkthrough and cannot run the real-model setup described in this section; see Pull and run from GHCR, which also covers what to do if no public image has been published yet.

Troubleshooting the local lab

npm run demo:local and npm run mcp:demo need Node 22.18+ (or 24.2+) and a running Docker daemon. They do not need .env.local, a Medplum account, or a model key. demo:local sets the local HAPI and scripted-walkthrough variables for its own processes.

SymptomCauseFix
Docker does not appear to be running. Start Docker Desktop (or your Docker daemon) and re-run this command.docker is on PATH, and docker info failed. The daemon is stopped or unreachable.Start Docker Desktop or the Docker daemon, then re-run the same command.
Could not start docker: spawn docker ENOENTThe docker binary is not on PATH.Install Docker, then re-run the command.
Compose reports that 127.0.0.1:8080 is already allocated, or address already in usePort 8080 is taken. docker-compose.yml binds HAPI to 127.0.0.1:8080.Stop the other listener, or run npm run demo:local:down if a previous stack holds the port, then re-run.
waiting for FHIR server at http://localhost:8080/fhir ... and then FHIR server at http://localhost:8080/fhir not ready after 5 minutes.The first HAPI boot initializes its database. That wait is five minutes (npm run fhir:wait).Leave the containers up and run npm run fhir:wait. If it times out again, read docker compose logs hapi, then npm run demo:local:down and re-run.
An old chart, a half-started stack, or compose errors about an existing containerA previous local stack is still present.npm run demo:local:down, then npm run demo:local or npm run mcp:demo.
npm warn EBADENGINE with required: { node: '^22.18.0 || >=24.2.0' }Node is outside package.json engines. .nvmrc is 22.18.0. Without engine-strict, npm warns and still installs.Install Node 22.18+ or 24.2+, then run npm install again.
Seeding needs write access to your Medplum project.npm run seed ran without FHIR_BACKEND=hapi and without Medplum credentials. demo:local sets the HAPI URL itself; a bare npm run seed does not.With the stack up: FHIR_BACKEND=hapi FHIR_BASE_URL=http://localhost:8080/fhir npm run seed. Or use npm run demo:local.
FHIR_BACKEND=hapi requires HAPI_BASE_URL or FHIR_BASE_URL (for example http://localhost:8080/fhir).HAPI mode is on and the base URL is unset.export FHIR_BASE_URL=http://localhost:8080/fhir (or HAPI_BASE_URL) and re-run.
A tool call says MEDPLUM_ACCESS_TOKEN is missing. The server still lists its tools. doctor reports that the configuration is invalid.@lastehr/mcp is in the default Medplum mode with no credential. Listing tools does not contact the backend.For this stack, set FHIR_BACKEND=hapi and FHIR_BASE_URL=http://localhost:8080/fhir instead of a Medplum token.

Medplum-backed demo

Use this path when you want real Medplum auth, AccessPolicy, and SMART launch behavior.

Prerequisites:

  • Node 22.18+ (or 24.2+)
  • A Medplum project
  • A Medplum ClientApplication with client credentials
  • One tool-capable model key
bash
git clone https://github.com/cbetz/last-ehr.git
cd last-ehr
npm install
cp .env.example .env.local
npm run seed
npm run dev

At minimum set:

bash
MEDPLUM_CLIENT_ID=...
MEDPLUM_CLIENT_SECRET=...
NEXT_PUBLIC_QUICKSTART=true
OPENAI_API_KEY=...

If you self-host Medplum, also set:

bash
MEDPLUM_BASE_URL=https://your-medplum.example/
NEXT_PUBLIC_MEDPLUM_BASE_URL=https://your-medplum.example/

Model providers

AI_PROVIDER=scripted above is deliberately not a model provider. It is a fixed local synthetic walkthrough. For a real agent, supported providers are intentionally limited to BAA-capable paths:

ProviderEnvNotes
OpenAIOPENAI_API_KEYDefault provider.
AnthropicAI_PROVIDER=anthropic, ANTHROPIC_API_KEYUses Anthropic models directly.
Amazon BedrockAI_PROVIDER=bedrock, MODEL_ID, AWS credential envRequires an explicit model id or inference profile.

The operator is responsible for signing the required BAA. A bare API key is not PHI-ready.

First prompts

In scripted mode, any submitted message starts the same fixed sequence. For a real model-backed agent, try these in order:

text
Find patients named Smith
Show me Maria Garcia's chart
Record a heart rate of 72 bpm for Maria Garcia
Add a note to Maria Garcia's chart that she reports feeling well with no complaints

The write prompts should stop at the approval card before anything is saved.

Epic and Oracle Health sandboxes

LASTEHR_EXPERIMENTAL_FHIR_ADAPTERS=1 turns on FHIR_BACKEND=epic and FHIR_BACKEND=oracle-health. With SMART Backend Services credentials an approved Observation is posted and read back. Without Oracle credentials the public open sandbox stays read-only and dry-run. The sandboxes do not support delete, so a posted write persists. Setup that fits in about ten minutes — register the app, generate a key, host a JWKS, set the env, approve one write — is in adapters/epic-cerner.md. These are not part of the supported matrix and not a clinical or compliance claim.

Other synthetic-evaluation backends

Beyond Medplum and the local HAPI stack, three more adapters are verified for synthetic evaluation: Firely Server (FHIR_BACKEND=firely, e.g. against the public sandbox at https://server.fire.ly), Aidbox (FHIR_BACKEND=aidbox, against a dev-licensed or hosted dev box), and Oystehr (FHIR_BACKEND=oystehr, against a developer-tier project). Setup, auth, and caveats for each are in the adapter guide; the boundaries are in the support matrix. None is an authenticated or PHI-ready path.

Want a concrete starting point?

Run the limited synthetic HAPI walkthrough before connecting a real backend.

Run locally