To expand a ValueSet, send GET [terminology-server]/ValueSet/$expand?url=[canonical-url]&filter=[search-text]&count=100 to retrieve a flat list of codes matching the filter from the value set
Parse the expansion.contains array in the returned ValueSet resource, extracting system, code, and display for each concept
To validate a specific code, send GET [terminology-server]/ValueSet/$validate-code?url=[valueset-url]&system=[code-system]&code=[code-value]&display=[display-text]
Check the Parameters response: the result parameter (boolean) indicates whether the code is valid in the value set; if false, the message parameter explains why
For $validate-code against a code system rather than a value set, use CodeSystem/$validate-code with the system and code parameters to verify the code exists in the code system regardless of value set membership
Known gotchas
Terminology servers may not support all SNOMED CT, LOINC, or RxNorm hierarchies locally — if the value set references an external code system the server does not host, the $expand may return an incomplete expansion or an error
Large value sets (e.g., all SNOMED CT clinical findings) cannot be fully expanded in a single request; use the offset and count parameters to paginate through the expansion, and check expansion.total against the number of retrieved codes to know when expansion is complete
The $validate-code operation returns result=true even if the display text does not match the canonical display — to validate display text, check the display parameter in the response and compare; a mismatch is a warning not a validation failure
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