[!NOTE] Informational, not clinical or coding advice. This server returns official code descriptions and billable/validity flags from public-domain federal releases to help you decode and look up codes. It is not medical advice, and a valid_billable result is not a coding or reimbursement decision. Always verify codes against the official source releases (CMS, CDC/NCHS, NLM) and your payer's rules before submitting a claim. The bundled data is only as current as the release baked into the build — call medcode_list_systems to see exactly which releases are active.

How it works

The code data is bundled inside the package — a single SQLite + FTS5 database (data/medical-codes.db) built at package-build time from the canonical federal source files and shipped in the npm tarball and Docker image. The server opens it read-only at startup and answers every tool call from disk.

That means the server is offline, keyless, and deterministic: no runtime network calls, no API key, no rate limit, single-tenant. The same inputs against the same bundled build always return the same output.

Bundled code systems

Only freely-redistributable, public-domain US federal code sets are bundled:

RxNorm bundles the current RxNorm normalized drug vocabulary — ingredients, brand names, clinical & branded drugs, and packs, with their NDC and ingredient/brand crosswalks. It is sourced at build time from the keyless RxNav REST API, which serves the public-domain normalized layer — never the UMLS-licensed source vocabularies, so it stays freely redistributable in an offline package. (The full UMLS RxNorm release, which pulls in those licensed sources, is intentionally excluded.) This powers medcode_map_codes' drug directions and direct NDC → drug decode in medcode_get_code.

CPT (AMA copyright) and SNOMED CT / LOINC (UMLS-license-gated) are intentionally absent — they are not freely redistributable, so they cannot ship in an offline package.

US scope. ICD-10-CM and ICD-10-PCS are the US clinical modifications, not the WHO ICD-10/ICD-11 base or another country's national modification.

Tools

Six tools organized goal-first — one per user action, with a system discriminator instead of a per-system tool for each of the bundled code sets. All are read-only.

medcode_get_code

Decode one or more codes seen in a claim, EHR field, or another health server's output. The 80% entry point.

• Accepts 1–50 codes; mixed systems are fine — each code's system is detected independently from its shape
• Decodes a National Drug Code (NDC) directly to its RxNorm product — hyphenated in an FDA segment configuration (4-4-2 0777-3105-02, 5-3-2, 5-4-1, or the 11-digit 5-4-2) or as bare 10/11 digits — offline via the bundled NDC↔RxNorm map, tagged source: "NDC"
• Partial success: resolved codes in found, unresolved in notFound with a per-code reason, so one bad code never fails the batch
• An explicit system overrides auto-detection when a value is genuinely ambiguous (an ambiguous code lists its candidateSystems)
• includeHierarchy attaches each code's parent and immediate children
• The resolved system is echoed on every result for chaining into medcode_map_codes or a billability check

medcode_search_codes

Find codes whose official descriptions match a described concept — the reverse of medcode_get_code.

• Every search term must appear (prefix-matched), so "diabetic neuropathy" returns codes mentioning both
• Filter by system, billableOnly (exclude headers/categories), and chapter
• Ranked by full-text relevance; results echo the resolved system per row
• Discloses truncation when the result hits the cap, and returns an explicit notice (with the parsed query) when nothing matched

medcode_check_code

Validate whether a code is safe to submit, before a claim goes out.

• Discriminated status: valid_billable, valid_not_billable, valid_header, or terminated
• A whyNot string explains the non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code")
• Validity vs. existence is split: a non-billable or terminated code is a successful result with a whyNot, not an error — only a code absent from every bundled system raises unknown_code

medcode_map_codes

Crosswalk a code across systems and within a hierarchy.

• Hierarchy directions: parents and children walk a code's prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full path (ICD-10-CM / HCPCS; ICD-10-PCS codes have no prefix parent)
• Drug directions (RxNorm): name_to_rxcui (drug name → RXCUI), ndc_to_rxcui / rxcui_to_ndc (NDC ↔ RXCUI; NDCs accepted hyphenated in an FDA segment configuration — 4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2 — or as bare 10/11 digits), rxcui_to_ingredients / rxcui_to_brands (RXCUI → ingredient/brand RXCUIs, each with the target's RxNorm name)
• Every result carries source provenance (which system or edge answered) so a chained call uses the right identifier
• children, name_to_rxcui, and rxcui_to_ndc can return large sets and paginate — a product can carry thousands of package NDCs; pass a response's nextCursor back as cursor (with an optional limit) to walk the full set

medcode_browse_hierarchy

Orient in an unfamiliar system or enumerate a category's specific codes, without a search term.

• With no node: top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values)
• With a node: its immediate children
• ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — only the top-level Section axis is browsable; positions 2–7 are context-dependent on the preceding axis path and aren't enumerable from a flat partial code

Features

Built on @cyanheads/mcp-ts-core: