Search for clinical notes: GET [base]/DocumentReference?patient=[id]&status=current&type=[LOINC-doc-type-code]; common LOINC document type codes include 34133-9 (Continuity of Care Document) and 11506-3 (Progress note).
Extract content[].attachment.url for each document; this may be a direct URL to retrieve the binary content or a reference to a Binary resource.
Retrieve the binary: if attachment.url is a relative or absolute FHIR URL, perform GET [url] with the same bearer token; the response is the raw document (PDF bytes or CDA XML).
Check attachment.contentType: 'application/pdf' for PDFs, 'text/xml' or 'application/xml' for CDA documents, 'text/plain' for plain text notes.
For CDA documents, parse the XML to extract the structured body or narrative text; the ClinicalDocument/component/structuredBody path contains coded section content.
Inspect context.encounter to link the note to its associated Encounter resource and context.period for the note's relevant date range.
Known gotchas
attachment.url may contain a pre-authenticated token that expires quickly; do not cache the URL itself, fetch the content immediately after retrieval.
Some servers return attachment.data (base64-encoded inline content) instead of a URL; check both fields and handle whichever is present.
DocumentReference does not guarantee the full note text is accessible via FHIR; some servers require a separate proprietary API or portal for note retrieval.
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