medical-codes-mcp-server

Decode one or more US medical codes to their official descriptions across ICD-10-CM (diagnoses), ICD-10-PCS (inpatient procedures), HCPCS Level II (supplies/drugs/services), and RxNorm (drugs, by RXCUI). Also decodes a National Drug Code (NDC) directly to its RxNorm product offline, tagged `source: "NDC"` — 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; any other segment widths are malformed and stay unresolved. Auto-detects the system from each code's shape; pass an explicit `system` only when a value is genuinely ambiguous. Accepts 1–50 codes and returns partial success: resolved codes in `found`, unresolved in `notFound` with a per-code reason, so one bad code never fails the batch. Set `includeHierarchy` to attach each code's parent and immediate children (with a `childrenTruncated` flag when a code has more children than the cap returns — walk the full set via medcode_browse_hierarchy or medcode_map_codes). The resolved `system` is echoed on every result for chaining into a billability check or a medcode_map_codes parents/children walk; a bare integer that resolves nowhere is named as a possible CPT / HCPCS Level I code, which is out of scope, except a bare 10/11-digit one, which is named as an NDC no bundled drug maps to; a code string that also exists in another bundled system carries `alsoInSystems` naming it, so a single answer to a colliding code is never mistaken for the only one.

{
  "type": "object",
  "properties": {
    "codes": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "A single code to decode (with or without dots), an RXCUI, or an NDC. Must not be blank or whitespace-only."
      },
      "description": "Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC decodes to its RxNorm product: hyphenated as 4-4-2, 5-3-2, 5-4-1, or 5-4-2, or as bare 10/11 digits."
    },
    "system": {
      "description": "Force every code to be looked up in this system, which also skips the NDC decode. Omit to auto-detect per code.",
      "type": "string",
      "enum": [
        "ICD10CM",
        "ICD10PCS",
        "HCPCS",
        "RXNORM"
      ]
    },
    "includeHierarchy": {
      "default": false,
      "description": "When true, attach each found code's parent and immediate children.",
      "type": "boolean"
    }
  },
  "required": [
    "codes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "description": "The system that answered: \"ICD10CM\", \"ICD10PCS\", \"HCPCS\", or \"RXNORM\". Pass it as `system` to medcode_check_code, or to medcode_map_codes on a parents/children walk; the map_codes drug directions accept only \"RXNORM\", which they need no `system` to reach."
          },
          "code": {
            "type": "string",
            "description": "The resolved code in display form (ICD-10-CM codes carry the dot, e.g. \"E11.9\")."
          },
          "description": {
            "description": "Official long description (falls back to the short description when no long form exists).",
            "type": [
              "string",
              "null"
            ]
          },
          "shortDescription": {
            "description": "Official short/abbreviated description, or null when none is on record. Always null for RxNorm, which publishes a single name.",
            "type": [
              "string",
              "null"
            ]
          },
          "billable": {
            "description": "True when the code is a billable leaf. False for headers/categories and non-billable codes. Null when the system has no billing concept (RxNorm).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "header": {
            "type": "boolean",
            "description": "True when the code is a non-billable category/header (ICD-10-CM) rather than a leaf code."
          },
          "chapter": {
            "description": "Chapter/range bucket the code belongs to, or null when not applicable. For RxNorm, the concept term type (IN, PIN, MIN, BN, SCD, SBD, GPCK, BPCK).",
            "type": [
              "string",
              "null"
            ]
          },
          "parent": {
            "description": "Immediate parent code (present only when includeHierarchy is true). Null at a root.",
            "type": [
              "string",
              "null"
            ]
          },
          "children": {
            "description": "Immediate child codes (present only when includeHierarchy is true).",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "system": {
                  "type": "string",
                  "description": "The system that answered: \"ICD10CM\", \"ICD10PCS\", \"HCPCS\", or \"RXNORM\". Pass it as `system` to medcode_check_code, or to medcode_map_codes on a parents/children walk; the map_codes drug directions accept only \"RXNORM\", which they need no `system` to reach."
                },
                "code": {
                  "type": "string",
                  "description": "The resolved code in display form (ICD-10-CM codes carry the dot, e.g. \"E11.9\")."
                },
                "description": {
                  "description": "Official long description (falls back to the short description when no long form exists).",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "shortDescription": {
                  "description": "Official short/abbreviated description, or null when none is on record. Always null for RxNorm, which publishes a single name.",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "billable": {
                  "description": "True when the code is a billable leaf. False for headers/categories and non-billable codes. Null when the system has no billing concept (RxNorm).",
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "header": {
                  "type": "boolean",
                  "description": "True when the code is a non-billable category/header (ICD-10-CM) rather than a leaf code."
                },
                "chapter": {
                  "description": "Chapter/range bucket the code belongs to, or null when not applicable. For RxNorm, the concept term type (IN, PIN, MIN, BN, SCD, SBD, GPCK, BPCK).",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "system",
                "code",
                "description",
                "shortDescription",
                "billable",
                "header",
                "chapter"
              ],
              "additionalProperties": false,
              "description": "A decoded code with its official descriptions and derived flags."
            }
          },
          "childrenTruncated": {
            "description": "True when the code has more immediate children than `children` carries — the list was capped at the server cap (present only when includeHierarchy is true). Retrieve the full child list with medcode_browse_hierarchy or medcode_map_codes (children) for this code.",
            "type": "boolean"
          },
          "source": {
            "description": "Resolution provenance when the input was not a direct code: \"NDC\" when an NDC was decoded to its RxNorm product via the NDC↔RxNorm map. Omitted for direct code lookups.",
            "type": "string"
          },
          "alsoInSystems": {
            "description": "Other bundled systems holding this same code string, present only when there is at least one. The result above is the system this code resolved in; the code is a DIFFERENT code in each system listed here — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to decode it there.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "system",
          "code",
          "description",
          "shortDescription",
          "billable",
          "header",
          "chapter"
        ],
        "additionalProperties": false,
        "description": "A decoded code, optionally with its parent/children and resolution source."
      },
      "description": "Successfully decoded codes, in request order."
    },
    "notFound": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The input code that could not be resolved."
          },
          "reason": {
            "type": "string",
            "description": "Why it could not be resolved (absent from every bundled system — for a bare integer, with a note that CPT / HCPCS Level I codes are out of scope — absent from the explicit `system` while another bundled system holds it, which is named, a well-formed NDC nothing maps to, hyphenated or as bare 10/11 digits, an NDC looked up under an explicit `system` that skips the NDC decode, or ambiguous across systems)."
          },
          "candidateSystems": {
            "description": "When ambiguous, the systems whose shape/content the code matched — re-call with one as `system`.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "code",
          "reason"
        ],
        "additionalProperties": false,
        "description": "An input code that did not resolve, with the reason it failed."
      },
      "description": "Codes that did not resolve, with per-code reasons."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_codes_found`: None of the requested codes resolved — in any bundled system, or in the explicit `system` when one is given (the message then names any other bundled system that holds a code). Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_codes_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "found",
        "notFound"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear — matched first as a token prefix, then as a substring so inflected and compound forms are also found (a "neuropathy" search surfaces "mononeuropathy"/"polyneuropathy" siblings too, not only a standalone "neuropathy" token). An RxNorm concept matches on its drug name alone, never its term type (SBD, IN, …) — narrow by type with `chapter`. Filter by `system` (ICD10CM/ICD10PCS/HCPCS/RXNORM), `billableOnly` to exclude headers/categories, and `chapter`. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, rank exact prefix matches ahead of substring-only matches with a deterministic tie-break, and disclose truncation with a `nextCursor`: pass it back as `cursor` to page through the full ranked set.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Clinical description to match, e.g. \"type 2 diabetes with neuropathy\". Must not be blank or whitespace-only."
    },
    "system": {
      "description": "Restrict results to one system. Omit to search all bundled systems.",
      "type": "string",
      "enum": [
        "ICD10CM",
        "ICD10PCS",
        "HCPCS",
        "RXNORM"
      ]
    },
    "billableOnly": {
      "default": false,
      "description": "When true, return only billable leaf codes (exclude headers/categories). RxNorm has no billing concept, so this excludes every RxNorm concept.",
      "type": "boolean"
    },
    "chapter": {
      "description": "Restrict to a chapter/range bucket (the value from a code's `chapter` field). Case-insensitive: surrounding whitespace is trimmed and the value is upper-cased to match how chapters are stored, and `appliedFilters.chapter` echoes the upper-cased value that actually ran. A blank or whitespace-only value carries no filtering intent and is treated as omitted, which the response discloses as `appliedFilters.chapter: null`.",
      "type": "string"
    },
    "limit": {
      "description": "Max codes per page. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of the same ranked result set. Omit for the first page.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "codes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "description": "The system the code belongs to, echoed for chaining."
          },
          "code": {
            "type": "string",
            "description": "The code in display form (ICD-10-CM carries the dot)."
          },
          "description": {
            "description": "Official long description (falls back to short when no long form exists).",
            "type": [
              "string",
              "null"
            ]
          },
          "shortDescription": {
            "description": "Official short description, or null when none is on record. Always null for RxNorm, which publishes a single name.",
            "type": [
              "string",
              "null"
            ]
          },
          "billable": {
            "description": "True when the code is a billable leaf. Null when the system has no billing concept (RxNorm).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "header": {
            "type": "boolean",
            "description": "True when the code is a non-billable category/header."
          },
          "chapter": {
            "description": "Chapter/range bucket, or null. For RxNorm, the concept term type (IN, PIN, MIN, BN, SCD, SBD, GPCK, BPCK).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "system",
          "code",
          "description",
          "shortDescription",
          "billable",
          "header",
          "chapter"
        ],
        "additionalProperties": false,
        "description": "A code matching the search query."
      },
      "description": "Matching codes, ranked by full-text relevance."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "The query as the server parsed it for matching."
    },
    "appliedFilters": {
      "type": "object",
      "properties": {
        "system": {
          "description": "System filter applied, or null.",
          "type": [
            "string",
            "null"
          ]
        },
        "billableOnly": {
          "type": "boolean",
          "description": "Whether the billable-only filter was applied."
        },
        "chapter": {
          "description": "Chapter filter applied, or null.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "system",
        "billableOnly",
        "chapter"
      ],
      "additionalProperties": false,
      "description": "Filters the server applied to the search."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when more matches exist beyond this page."
    },
    "shown": {
      "type": "number",
      "description": "Number of codes returned on this page."
    },
    "cap": {
      "type": "number",
      "description": "The page size that was applied."
    },
    "nextCursor": {
      "description": "Opaque token to pass back as `cursor` for the next page. Present only when more matches exist beyond this page.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when nothing matched — echoes the query and suggests how to broaden, or names `billableOnly` as the cause when the searched system has no billing concept.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "codes",
        "effectiveQuery",
        "appliedFilters",
        "truncated",
        "shown",
        "cap"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Validate whether a US medical code exists, is current, and is billable in the active bundled release. Returns a discriminated status — valid_billable, valid_not_billable, valid_header, valid, or terminated — with a `whyNot` explaining non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code"). This is the detail a coder needs before submitting a claim. RxNorm has no billing concept, so a current RxNorm concept is `valid` with `billable: null` and no billing verdict. Auto-detects the system from the code's shape; pass an explicit `system` to disambiguate. A non-billable or terminated code is a successful result with a whyNot, not an error — only a code absent from the named or detected system raises unknown_code, which names the other bundled system when one holds the code. A code string that also exists in another bundled system carries `alsoInSystems` naming it, since the verdict applies only to the system that answered.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "description": "The code to validate, with or without dots. Must not be blank or whitespace-only."
    },
    "system": {
      "description": "Force the lookup into this system. Omit to auto-detect from the code's shape.",
      "type": "string",
      "enum": [
        "ICD10CM",
        "ICD10PCS",
        "HCPCS",
        "RXNORM"
      ]
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "system": {
      "type": "string",
      "description": "The system the code was resolved in, echoed for chaining."
    },
    "code": {
      "type": "string",
      "description": "The code in display form (ICD-10-CM carries the dot)."
    },
    "status": {
      "type": "string",
      "enum": [
        "valid_billable",
        "valid_not_billable",
        "valid_header",
        "valid",
        "terminated"
      ],
      "description": "Validity status. valid_billable = submit as-is; valid_header/valid_not_billable = needs a more specific code; valid = exists and is current in a system with no billing concept (RxNorm), so there is no billing verdict; terminated = retired."
    },
    "billable": {
      "description": "True only when status is valid_billable. Null when status is valid — the system has no billing concept.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "whyNot": {
      "description": "Explanation for non-billable/terminated statuses, or null when valid_billable or valid.",
      "type": [
        "string",
        "null"
      ]
    },
    "alsoInSystems": {
      "description": "Other bundled systems holding this same code string, present only when there is at least one. The verdict above is for the system this code resolved in; the code is a DIFFERENT code in each system listed here, with its own billability — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to validate it there.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `unknown_code`: The code does not exist in the named or detected system. `ambiguous_system`: The code is present in more than one bundled system and no `system` was given. Other values are possible when a failure originates below the handler.",
              "examples": [
                "unknown_code",
                "ambiguous_system"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "system",
        "code",
        "status",
        "billable",
        "whyNot"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Crosswalk a US medical code or drug 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 ancestor or descendant path (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent, and RxNorm concepts no code hierarchy). A resolvable source with no edge in the requested direction is a successful empty result with a notice, not an error. A source code string that also exists in another bundled system carries `alsoInSystems` naming it, since only the resolved system's hierarchy was walked. Drug directions (RxNorm): `name_to_rxcui` (drug name → RXCUI), `ndc_to_rxcui` and `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; `ndc_to_rxcui` names the product it decoded to), `rxcui_to_ingredients` and `rxcui_to_brands` (RXCUI → ingredient/brand RXCUIs, each with the target's RxNorm name and its `conceptType` — read that before counting a combination product's ingredients). Drug-class directions (RxClass): `rxcui_to_classes` (RXCUI → its classes: pharmacologic class, mechanism of action, physiologic effect, pharmacokinetics, therapeutic category, chemical structure, the diseases it may treat, prevent, diagnose, or induce or is contraindicated with, VA class, DEA controlled-substance schedule, CDC vaccine code; a drug product also carries its ingredients' classes, naming the ingredient in `via`, while DEA schedules are recorded only on drug products and VA classes almost only there, so map a product for those) and `class_to_rxcuis` (class ID → its direct member RXCUIs, each with its RxNorm name and `conceptType`). Each class hit carries `classType`, `source` (the RxClass source asserting it), and `relation` — a `ci_` relation is a contraindication, not an indication; narrow either direction with `classType`. Every result carries `source` provenance (which system or edge answered) so a chained call (e.g. into openfda with a resolved NDC) uses the right identifier. The `children`, `name_to_rxcui`, `rxcui_to_ndc`, `rxcui_to_classes`, and `class_to_rxcuis` directions can return large sets and paginate: a `nextCursor` in the response is passed back as `cursor` (with an optional `limit` page size) to walk the full set. A field the direction does not use is rejected with `field_not_applicable`: `limit` and `cursor` on the point directions, `classType` outside the class directions, and a `system` other than RXNORM on the drug and class directions.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "minLength": 1,
      "description": "The source value: a code (for parents/children), a drug name, an NDC, an RXCUI, or an RxClass class ID (for class_to_rxcuis). Must not be blank or whitespace-only."
    },
    "direction": {
      "type": "string",
      "enum": [
        "parents",
        "children",
        "name_to_rxcui",
        "ndc_to_rxcui",
        "rxcui_to_ndc",
        "rxcui_to_ingredients",
        "rxcui_to_brands",
        "rxcui_to_classes",
        "class_to_rxcuis"
      ],
      "description": "What to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks; rxcui_to_classes and class_to_rxcuis are RxClass drug-class crosswalks."
    },
    "system": {
      "description": "For parents/children, force the source code into this system. Omit to auto-detect. The drug and class directions resolve in RxNorm and accept only \"RXNORM\" (no effect); any other value there is rejected.",
      "type": "string",
      "enum": [
        "ICD10CM",
        "ICD10PCS",
        "HCPCS",
        "RXNORM"
      ]
    },
    "classType": {
      "description": "For rxcui_to_classes and class_to_rxcuis only: keep only classes of this RxClass type — EPC (FDA established pharmacologic class), MOA (mechanism of action), PE (physiologic effect), PK (pharmacokinetics), TC (therapeutic category), CHEM (chemical structure), DISEASE (diseases the drug may treat, prevent, diagnose, or induce, or is contraindicated with), VA (VA drug class, recorded almost only on drug products), SCHEDULE (DEA controlled-substance schedule, recorded on drug products only), CVX (CDC vaccine code). Omit for every type. Rejected on every other direction.",
      "type": "string",
      "enum": [
        "EPC",
        "MOA",
        "PE",
        "PK",
        "TC",
        "CHEM",
        "DISEASE",
        "VA",
        "SCHEDULE",
        "CVX"
      ]
    },
    "limit": {
      "description": "Max results per page, for the paginated directions only (children, name_to_rxcui, rxcui_to_ndc, rxcui_to_classes, class_to_rxcuis). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Rejected on every other direction.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's `nextCursor`, for the paginated directions only (children, name_to_rxcui, rxcui_to_ndc, rxcui_to_classes, class_to_rxcuis). Omit for the first page; an empty string counts as omitted. A non-empty cursor on any other direction is rejected.",
      "type": "string"
    }
  },
  "required": [
    "from",
    "direction"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "The source value, echoed back."
    },
    "direction": {
      "type": "string",
      "description": "The mapping direction that was applied."
    },
    "resolvedSystem": {
      "description": "The system the source resolved in, or null when not system-scoped.",
      "type": [
        "string",
        "null"
      ]
    },
    "alsoInSystems": {
      "description": "Other bundled systems holding the same `from` code string, present only when there is at least one (hierarchy directions only — a drug name, NDC, or RXCUI is not system-scoped). The hits above were walked in `resolvedSystem` alone; the code is a DIFFERENT code with a different hierarchy in each system listed here — \"B00\" is the ICD-10-CM category \"Herpesviral [herpes simplex] infections\" and also the ICD-10-PCS table row \"Imaging, Central Nervous System, Plain Radiography\". Re-call with `system` set to one of these values to walk it there.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Which system or relationship edge produced this hit (e.g. \"ICD10CM\", \"has_ingredient\", \"NDC\"). On the class directions, the RxClass source asserting the drug–class edge: \"MEDRT\" (VA MED-RT), \"FDASPL\" (FDA structured product labels), \"FMTSME\" (Federal Medication Terminologies), \"VA\" (VA National Formulary classes), \"RXNORM\" (DEA schedules as RxNorm records them), or \"CDC\" (CVX vaccine codes)."
          },
          "system": {
            "description": "The code system of the target value, or null when the target is not a system code (an NDC, or an RxClass class ID).",
            "type": [
              "string",
              "null"
            ]
          },
          "value": {
            "type": "string",
            "description": "The mapped target value (a code, RXCUI, NDC, or RxClass class ID)."
          },
          "description": {
            "description": "Description of the target when available: the code description for hierarchy hits, the official RxNorm name for the `name_to_rxcui`, `ndc_to_rxcui`, `rxcui_to_ingredients`, `rxcui_to_brands`, and `class_to_rxcuis` drug concepts, and the class name for `rxcui_to_classes`. Absent for `rxcui_to_ndc`, whose targets are package identifiers with no description of their own.",
            "type": "string"
          },
          "conceptType": {
            "description": "The target concept's RxNorm type, present on `rxcui_to_ingredients`, `rxcui_to_brands`, and `class_to_rxcuis` hits only. A class member may be any drug concept: an ingredient type below, or a drug product — \"SCD\"/\"SBD\" (clinical/branded drug) or \"GPCK\"/\"BPCK\" (generic/branded pack). Otherwise \"IN\" (ingredient), \"PIN\" (precise ingredient — a specific salt, ester, or isomer of an ingredient), \"MIN\" (multiple ingredients — a concept naming a combination, never a substance within it), or \"BN\" (brand name). Ingredient hits mix the first three, so the hit count is not the substance count: a \"MIN\" hit is the grouping concept and never counts, and a \"PIN\" names a form of a substance rather than an extra one — usually alongside the \"IN\" it refines, though two \"PIN\" esters can share a single \"IN\". Counting the \"IN\" hits is the closest reading, and under-counts those shared cases.",
            "type": "string"
          },
          "classType": {
            "description": "The RxClass class type, on `rxcui_to_classes` and `class_to_rxcuis` hits only — the values the `classType` input takes.",
            "type": "string",
            "enum": [
              "EPC",
              "MOA",
              "PE",
              "PK",
              "TC",
              "CHEM",
              "DISEASE",
              "VA",
              "SCHEDULE",
              "CVX"
            ]
          },
          "relation": {
            "description": "The RxClass relationship between the drug and the class, on `rxcui_to_classes` and `class_to_rxcuis` hits only: has_epc, has_moa, has_pe, has_pk, site_of_metabolism, has_tc, has_ingredient / has_chemical_structure / has_active_metabolites (CHEM), may_treat / may_prevent / may_diagnose / induces (DISEASE), has_vaclass / has_vaclass_extended, has_schedule, isa_cvx. A `ci_` relation (ci_with, ci_moa, ci_pe, ci_chemclass) is a contraindication: the drug is contraindicated with that disease or class — never an indication, and never class membership.",
            "type": "string"
          },
          "via": {
            "description": "On `rxcui_to_classes` hits only: the ingredient RXCUI a drug product inherits this class through — RxClass attaches most classes to ingredients. Absent when the class attaches to the source RXCUI itself. When several ingredients carry the same class, names an ingredient (\"IN\") over its precise ingredient (\"PIN\"), then the lowest RXCUI.",
            "type": "string"
          }
        },
        "required": [
          "source",
          "system",
          "value"
        ],
        "additionalProperties": false,
        "description": "One crosswalk result tagged with the edge that produced it."
      },
      "description": "Crosswalk results, each tagged with the edge that produced it."
    },
    "truncated": {
      "description": "Paginated directions (children, name_to_rxcui, rxcui_to_ndc, rxcui_to_classes, class_to_rxcuis) only: true when more results exist beyond this page.",
      "type": "boolean"
    },
    "shown": {
      "description": "Paginated directions only: number of hits returned on this page.",
      "type": "number"
    },
    "cap": {
      "description": "Paginated directions only: the page size that was applied.",
      "type": "number"
    },
    "nextCursor": {
      "description": "Paginated directions only: opaque token to pass back as `cursor` for the next page. Present only when more results exist beyond this page.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance whenever a resolvable source returns no hits, naming which of the two causes applies: it has no edge in the requested direction (a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent; RxNorm concepts have no code hierarchy; no bundled class, or none of the requested `classType`, covers the RXCUI; a class has no direct member), or the `cursor` starts past the last page of a direction that does have results.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `field_not_applicable`: A `system`, `classType`, `limit`, or `cursor` was sent on a direction that does not use it. `no_mapping`: The source value did not resolve to any bundled code, drug, or class. `direction_unavailable`: A drug-crosswalk direction was requested but this build carries no RxNorm tables, or a class direction was requested but it carries no RxClass class layer. `ambiguous_system`: The source code is present in more than one system and no `system` was given. Other values are possible when a failure originates below the handler.",
              "examples": [
                "field_not_applicable",
                "no_mapping",
                "direction_unavailable",
                "ambiguous_system"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "from",
        "direction",
        "resolvedSystem",
        "hits"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Walk a US medical code system's hierarchy for discovery without a search term. With no `node`, returns the top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values). With a `node`, returns 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 — each of its 7 characters is an independent axis (section, body system, root operation, body part, approach, device, qualifier), but only the top-level Section axis is browsable (omit `node`): positions 2–7 are context-dependent on the preceding axis path and are not enumerable from a flat partial code. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes. A large child set paginates: when the response carries a `nextCursor`, pass it back as `cursor` to fetch the next page.

{
  "type": "object",
  "properties": {
    "system": {
      "type": "string",
      "enum": [
        "ICD10CM",
        "ICD10PCS",
        "HCPCS",
        "RXNORM"
      ],
      "description": "The code system to browse."
    },
    "node": {
      "description": "A node to expand — or omit / pass an empty string for the top level. For ICD-10-CM/HCPCS, a code whose children to list; ICD-10-PCS supports only top-level Section browsing. Must not be blank or whitespace-only when provided.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "minLength": 1,
          "description": "A code whose children to list (ICD-10-CM/HCPCS). ICD-10-PCS supports only top-level Section browsing — a partial PCS code does not expand to next-position axis values."
        }
      ]
    },
    "limit": {
      "description": "Max entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.",
      "type": "string"
    }
  },
  "required": [
    "system"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "codes",
        "axes"
      ],
      "description": "\"codes\" for prefix-hierarchy children (ICD-10-CM/HCPCS); \"axes\" for ICD-10-PCS axis values."
    },
    "codes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "description": "The system the node belongs to."
          },
          "code": {
            "type": "string",
            "description": "The child code in display form."
          },
          "description": {
            "description": "Official long description, or null.",
            "type": [
              "string",
              "null"
            ]
          },
          "shortDescription": {
            "description": "Official short description, or null.",
            "type": [
              "string",
              "null"
            ]
          },
          "billable": {
            "description": "True when the code is a billable leaf. Null when the system has no billing concept.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "header": {
            "type": "boolean",
            "description": "True when the code is a non-billable category/header."
          },
          "chapter": {
            "description": "Chapter/range bucket, or null.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "system",
          "code",
          "description",
          "shortDescription",
          "billable",
          "header",
          "chapter"
        ],
        "additionalProperties": false,
        "description": "A child code in a prefix hierarchy (ICD-10-CM/HCPCS)."
      },
      "description": "Child codes under the requested node or top level. Empty when kind is \"axes\"."
    },
    "axes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "position": {
            "type": "number",
            "description": "The 1-based character position in the ICD-10-PCS code."
          },
          "value": {
            "type": "string",
            "description": "The single-character axis value valid at this position."
          },
          "meaning": {
            "type": "string",
            "description": "What this axis value means at this position."
          }
        },
        "required": [
          "position",
          "value",
          "meaning"
        ],
        "additionalProperties": false,
        "description": "A valid ICD-10-PCS axis value at a given character position."
      },
      "description": "The top-level ICD-10-PCS Section axis values (only the Section axis is enumerable). Empty when kind is \"codes\"."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when more entries exist beyond this page."
    },
    "shown": {
      "type": "number",
      "description": "Number of entries returned on this page (codes or axes)."
    },
    "cap": {
      "type": "number",
      "description": "The page size that was applied."
    },
    "nextCursor": {
      "description": "Opaque token to pass back as `cursor` for the next page. Present only when more entries exist beyond this page.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when a node has no children/axes — suggests the top level or a valid node.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `unknown_node`: The node does not exist in the system — for ICD-10-PCS, also when it uses a character outside the axis alphabet or begins no bundled code. Other values are possible when a failure originates below the handler.",
              "examples": [
                "unknown_node"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "kind",
        "codes",
        "axes",
        "truncated",
        "shown",
        "cap"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the bundled US medical code systems with their release identifiers, effective dates, and code counts, and the RxClass drug-class layer the class crosswalks read, with each source’s version. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, RxNorm normalized set, and RxClass sources are active before acting on any decode, search, or crosswalk result. The corpus is offline and built at package-build time — this call reports exactly which release is baked into the running server. ICD-10-CM/PCS are the US clinical modifications, not the ICD-10/ICD-11 base.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "systems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "description": "System identifier, e.g. \"ICD10CM\", \"ICD10PCS\", \"HCPCS\", \"RXNORM\"."
          },
          "label": {
            "type": "string",
            "description": "Human-readable system name, e.g. \"ICD-10-CM\"."
          },
          "releaseId": {
            "type": "string",
            "description": "Release/version identifier baked into this build, e.g. \"ICD-10-CM FY2026\"."
          },
          "effectiveStart": {
            "description": "First date this release is effective (YYYY-MM-DD), or null if not recorded.",
            "type": [
              "string",
              "null"
            ]
          },
          "effectiveEnd": {
            "description": "Last date this release is effective (YYYY-MM-DD), or null if open-ended.",
            "type": [
              "string",
              "null"
            ]
          },
          "codeCount": {
            "type": "number",
            "description": "Number of code rows bundled for this system."
          },
          "sourceUrl": {
            "description": "Canonical .gov source the release was built from, or null.",
            "type": [
              "string",
              "null"
            ]
          },
          "builtAt": {
            "type": "string",
            "description": "ISO 8601 timestamp of this system’s data. For ICD-10-CM, ICD-10-PCS, and HCPCS, the time the index was built from the release named in `releaseId`. For RxNorm, which publishes no release label, the date the RxNav snapshot was fetched — how current its drug data is, unchanged by a rebuild from the same snapshot."
          }
        },
        "required": [
          "system",
          "label",
          "releaseId",
          "effectiveStart",
          "effectiveEnd",
          "codeCount",
          "sourceUrl",
          "builtAt"
        ],
        "additionalProperties": false,
        "description": "Provenance for one bundled code system."
      },
      "description": "One entry per bundled code system, in canonical order — the systems the `system` inputs of the other tools accept."
    },
    "classLayer": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "classCount": {
              "type": "number",
              "description": "RxClass class nodes bundled, including hierarchy nodes with no direct member."
            },
            "edgeCount": {
              "type": "number",
              "description": "Drug–class edges bundled, across every source."
            },
            "sourceUrl": {
              "type": "string",
              "description": "The RxClass API the layer was fetched from."
            },
            "sources": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "description": "The RxClass source, as class hits carry it in `source`: MEDRT, FDASPL, FMTSME, VA, RXNORM (DEA schedules), or CDC (CVX)."
                  },
                  "version": {
                    "description": "The release RxClass reports for this source, or null when it publishes none.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "classCount": {
                    "type": "number",
                    "description": "Classes this source asserts at least one bundled edge to."
                  },
                  "edgeCount": {
                    "type": "number",
                    "description": "Drug–class edges this source contributes."
                  },
                  "fetchedAt": {
                    "type": "string",
                    "description": "ISO 8601 date the RxClass snapshot was fetched — how current the class edges are."
                  }
                },
                "required": [
                  "source",
                  "version",
                  "classCount",
                  "edgeCount",
                  "fetchedAt"
                ],
                "additionalProperties": false,
                "description": "Provenance for one bundled RxClass source."
              },
              "description": "One entry per bundled RxClass source."
            }
          },
          "required": [
            "classCount",
            "edgeCount",
            "sourceUrl",
            "sources"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The RxClass drug-class layer the rxcui_to_classes and class_to_rxcuis directions of medcode_map_codes read — not a code system, so it has no entry in `systems`. Null when this build carries no class layer."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "systems",
        "classLayer"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}