Snowstorm Lite FHIR Terminology Server

A fast FHIR Terminology Server for SNOMED CT with a small memory footprint.

• Use Case
• Features
• Limitations
• Technical Details
• Quick Start
• MCP (Model Context Protocol) Support
• Try the API with Postman
• Roadmap

Use Case

• Scaling architecture
• Supporting user data input with SNOMED CT driven search where responsiveness is critical
• Using SNOMED CT offline:
  • Locations with poor connectivity and limited machine memory
  • Trusted research environments that are not able to make external API requests
• Not suitable as a national terminology server

Features

• Host a single SNOMED CT Edition with incredible speed
• SNOMED query support using ECL Core, a subset of ECL
  • Includes the top and bottom operators !!> and !!< (bottom is not supported with a wildcard)
• ECL utility endpoints for ECL builder applications (parse ECL to JSON model and convert back)
• Perfect for search
  • Most relevant results first
  • Supports terminology binding
  • Multiple language support with configurable character folding
• FHIR Terminology Operations
  • CodeSystem lookup
    • Including parents, children, designations, normal form
  • CodeSystem $validate-code
  • ValueSet create/edit/delete, $expand and $validate-code
  • ConceptMap create/edit/delete and $translate
  • SNOMED CT Implicit Value Sets
    • SNOMED CT isa and ecl filters are supported
  • SNOMED CT Implicit Maps
  • Automatic deployment of SNOMED CT from MLDS

Limitations

• Only supports one release of SNOMED CT Edition at this time
• Does not support SNOMED CT authoring or the SNOMED CT Browser

Technical Details

• Minimal memory footprint is perfect for autoscaling
  • After creating the index the app can run with just 500mb memory
• Self-contained application using Apache Lucene™
• Uses Spring Boot and HAPI FHIR Frameworks
• Requires JDK 17

Quick Start

No configuration files are required to get started. Run Snowstorm Lite in your local Docker:

docker pull snomedinternational/snowstorm-lite:latest
docker run -p 8080:8080 --name=snowstorm-lite \
  -v snowstorm-lite-volume:/app/lucene-index \
  snomedinternational/snowstorm-lite:latest \
  --index.path=lucene-index/data

Open the Dashboard at http://localhost:8080/ and sign in with the default admin credentials, admin / snowstormLITE.

Optionally choose your own admin password by adding --admin.password=yourAdminPassword to the docker run command above.

Option 1: Using a SNOMED Syndication Service

If you have access to the SNOMED International MLDS service then Snowstorm Lite can download a release automatically.

• Use the Dashboard to pull an edition by navigating to http://localhost:8080/, logging in as admin, selecting the Syndication option, entering your MLDS credentials and choosing an Edition.
• Alternatively download an edition automatically during startup by adding these options to the docker run command: --syndicate --syndication.username=your-mlds-username --syndication.password=your-mlds-password --version-uri=http://snomed.info/sct/900000000000207008. Set --version-uri to the URI of the SNOMED Edition to be loaded, see SNOMED Edition URI Examples.

Option 2: Using a SNOMED Archive File

If you have access to a SNOMED CT Edition release archive this can be imported, using the Dashboard or the command line.

Upload a SNOMED CT package:

curl -u admin:snowstormLITE \
  --form file=@SnomedCT_InternationalRF2_PRODUCTION_20250101T120000Z.zip \
  --form version-uri="http://snomed.info/sct/900000000000207008/version/20250101" \
  http://localhost:8080/fhir-admin/load-package

---

Importing a SNOMED CT release takes about 5 minutes.

When the import is complete Snowstorm Lite will be ready for use! The FHIR interface is here: http://localhost:8080/fhir.

It is possible to import extension or derivative packages.

It is also possible to deploy as a Java application, without Docker.

ECL Utility Endpoints

Snowstorm Lite provides utility endpoints for ECL builder applications, matching the Snowstorm API. These support the same ECL Core subset used by FHIR ValueSet $expand (via ?fhir_vs=ecl/). Concept and term validation is not performed.

Parse ECL to JSON model

curl -X POST http://localhost:8080/util/ecl-string-to-model \
  -H "Content-Type: text/plain" \
  --data-raw "<< 404684003 |Clinical finding|"

Convert JSON model to ECL string

curl -X POST http://localhost:8080/util/ecl-model-to-string \
  -H "Content-Type: application/json" \
  -d '{"operator":"descendantorselfof","conceptId":"404684003","term":"Clinical finding","wildcard":false,"returnAllMemberFields":false}'

Response: {"eclString":"<< 404684003 |Clinical finding|"}

Unsupported ECL features (attribute groups, concept/description/member filters, member fields, etc.) return HTTP 501.

The Dashboard ValueSet builder includes a structured ECL builder modal (open from ECL expression criteria rows) that uses these endpoints for parse/apply round-trips.

MCP (Model Context Protocol) Support

Snowstorm Lite now supports the Model Context Protocol, allowing AI assistants like Claude to interact with SNOMED CT terminology data through standardized tools.

Available MCP Tools

1. lookup_snomed_code - Retrieve detailed information about a SNOMED CT concept

   • Parameters: code (required), language (optional, default: "en")
   • Returns: Complete concept details including display name, FSN, descriptions, parents, children, relationships

2. search_snomed_codes - Search concepts by code prefix or description text

   • Parameters: query (required), activeOnly (optional, default: true), language (optional), limit (optional, max: 100)
   • Returns: List of matching concepts with display names and active status

3. validate_snomed_code - Verify if a code exists and check its active status

   • Parameters: code (required)
   • Returns: Validation result with existence and active status

4. check_snomed_subsumption - Check hierarchical relationships between concepts

   • Parameters: codeA (required), codeB (required)
   • Returns: Subsumption outcome ("subsumes", "subsumed-by", "equivalent", "not-subsumed")

Configuration

The MCP server is enabled by default and accessible via SSE (Server-Sent Events) transport. Configure in application.properties:

spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=Snowstorm Lite SNOMED CT Server

Connecting an MCP Client

1. Start Snowstorm Lite (see Quick Start above)
2. Configure your MCP client to connect to: http://localhost:8080/sse
   • For HTTPS (via nginx): https://localhost/sse
3. The client will discover available tools automatically

Note: The MCP server uses two endpoints:

• /sse - For receiving server-sent events (this is the connection URL for MCP clients)
• /mcp/message - For sending messages to the server (used internally by the client)

Example Usage (via Claude)

User: Look up SNOMED CT code 73211009
Claude: [Uses lookup_snomed_code tool]
Result: 73211009 - Diabetes mellitus (disorder)
        Active concept with FSN, synonyms, parents, and relationships...

User: Search for heart attack concepts
Claude: [Uses search_snomed_codes tool with query="heart attack"]
Result: Found 15 matching concepts including:
        - 22298006 - Myocardial infarction (disorder)
        - 57054005 - Acute myocardial infarction (disorder)
        ...

Postman

This Postman collection allows you to try the various API functions of the Snowstorm Lite server. It's similar to a Swagger UI.
You will need a local Snowstorm Lite instance running.

Roadmap

• Nothing currently planned.

Full ECL support is not planned. Snowstorm Lite supports the most often used ECL features without the full complexity and memory demands of the complete ECL specification.