Confirm the target FHIR server supports $import by checking its CapabilityStatement or documentation; note that $import is a proposed operation and server support varies significantly
Stage the FHIR NDJSON files in a location accessible to the server (e.g., a cloud storage bucket with a pre-signed URL or a location the server can pull from)
Construct a Parameters body for the $import request specifying inputFormat (application/fhir+ndjson), inputSource (the base URL of the staged files), and storageDetail (type and credentials if needed)
POST to [base]/$import with Prefer: respond-async; expect a 202 Accepted with a Content-Location header for status polling
Poll the Content-Location URL; the server returns 202 with progress details until import completes, then 200 with a manifest describing success and error counts per resource type
Check the error output files in the manifest for rejected resources; parse each error NDJSON line which typically contains an OperationOutcome explaining the rejection reason
Known gotchas
$import is not a finalized FHIR standard operation — it is defined by the Bulk Data IG as a proposal; server implementations differ in their request format, authentication requirements, and error handling
Large imports may time out or be throttled by the server; implement retry logic and use the status polling endpoint rather than assuming completion within a fixed window
Existing resources with the same id may be overwritten or rejected depending on server configuration; clarify the server's upsert-vs-reject behavior before bulk importing data that may overlap existing records
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp