Confirm that the target FHIR server supports the $docref operation by checking the CapabilityStatement for the Patient resource operation list.
Issue the operation request: POST [base]/Patient/[id]/$docref (or GET with query parameters depending on the server's implementation) with optional parameters such as start, end, and type to filter the returned documents by date range or document type.
Evaluate the returned searchset Bundle of DocumentReference resources; each DocumentReference describes an available clinical document with metadata and a content.attachment.url for retrieval.
Retrieve individual documents by issuing HTTP GET requests to the URLs in DocumentReference.content.attachment.url, handling the returned content type appropriately (Binary, CDA, PDF, FHIR document).
Handle the case where the server generates documents on-demand (e.g., assembling a C-CDA from structured data at query time) rather than retrieving pre-existing stored documents.
Apply date range and type filters to limit the response to clinically relevant documents and avoid retrieving unnecessary large volumes of historical documents.
Known gotchas
The $docref operation parameters (start, end, type) may not be supported by all implementations — check the CapabilityStatement's operation definition for supported parameters.
Some EHR implementations generate the C-CDA document at query time from structured data, which may introduce latency for the response; set appropriate timeouts.
The US Core $docref operation has specific guidance on parameter interpretation — review the current US Core IG for required vs. optional parameters and expected response format.
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