Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Get Medical Code

medcode_get_code
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codesYesCodes 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.
systemNoForce every code to be looked up in this system, which also skips the NDC decode. Omit to auto-detect per code.
includeHierarchyNoWhen true, attach each found code's parent and immediate children.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
foundNoSuccessfully decoded codes, in request order.
notFoundNoCodes that did not resolve, with per-code reasons.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • changedInput schema / properties / system / description
      Previous value: -"Force every code to be looked up in this system. Omit to auto-detect per code."New value: +"Force every code to be looked up in this system, which also skips the NDC decode. Omit to auto-detect per code."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_codes_found`: None of the requested codes exist in any bundled system. Other values are possible when a failure originates below the handler."New value: +"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."
    • changedOutput schema / properties / found / items / properties / billable / description
      Previous value: -"True when the code is a billable leaf. False for headers/categories and non-billable codes."New value: +"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)."
    • changedOutput schema / properties / found / items / properties / billable / type
      Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
    • changedOutput schema / properties / found / items / properties / chapter / description
      Previous value: -"Chapter/range bucket the code belongs to, or null when not applicable."New value: +"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)."
    • changedOutput schema / properties / found / items / properties / children / items / properties / billable / description
      Previous value: -"True when the code is a billable leaf. False for headers/categories and non-billable codes."New value: +"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)."
    • changedOutput schema / properties / found / items / properties / children / items / properties / billable / type
      Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
    • changedOutput schema / properties / found / items / properties / children / items / properties / chapter / description
      Previous value: -"Chapter/range bucket the code belongs to, or null when not applicable."New value: +"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)."
    • changedOutput schema / properties / found / items / properties / children / items / properties / shortDescription / description
      Previous value: -"Official short/abbreviated description, or null when none is on record."New value: +"Official short/abbreviated description, or null when none is on record. Always null for RxNorm, which publishes a single name."
    • changedOutput schema / properties / found / items / properties / children / items / properties / system / description
      Previous value: -"The system that answered, echoed for chaining: \"ICD10CM\", \"ICD10PCS\", \"HCPCS\", or \"RXNORM\"."New value: +"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."
    • changedOutput schema / properties / found / items / properties / shortDescription / description
      Previous value: -"Official short/abbreviated description, or null when none is on record."New value: +"Official short/abbreviated description, or null when none is on record. Always null for RxNorm, which publishes a single name."
    • changedOutput schema / properties / found / items / properties / system / description
      Previous value: -"The system that answered, echoed for chaining: \"ICD10CM\", \"ICD10PCS\", \"HCPCS\", or \"RXNORM\"."New value: +"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."
    • changedOutput schema / properties / notFound / items / properties / reason / description
      Previous value: -"Why it could not be resolved (absent from every bundled system, a well-formed NDC nothing maps to, or ambiguous across systems)."New value: +"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)."
  2. Changed14 schema fields changed
    • removedOutput schema / properties / found / items / properties / chapter / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / chapter / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / children / items / properties / chapter / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / children / items / properties / chapter / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / children / items / properties / description / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / children / items / properties / description / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / children / items / properties / shortDescription / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / children / items / properties / shortDescription / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / description / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / description / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / parent / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / parent / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / found / items / properties / shortDescription / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / found / items / properties / shortDescription / type
      Added value: +[
+  "string",
+  "null"
+]
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "found",
+      "notFound"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_codes_found`: None of the requested codes exist in any bundled system. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_codes_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "found",
-  "notFound"
-]
  4. Changed3 schema fields changed
    • changedInput schema / properties / codes / description
      Previous value: -"Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product."New value: +"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."
    • addedOutput schema / properties / found / items / properties / alsoInSystems
      Added value: +{
+  "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.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / notFound / items / properties / reason / description
      Previous value: -"Why it could not be resolved (unknown shape, not in the bundled release, or ambiguous)."New value: +"Why it could not be resolved (absent from every bundled system, a well-formed NDC nothing maps to, or ambiguous across systems)."
  5. Changed1 schema field changed
    • changedInput schema / properties / codes / items / description
      Previous value: -"A single code to decode (with or without dots), an RXCUI, or an NDC."New value: +"A single code to decode (with or without dots), an RXCUI, or an NDC. Must not be blank or whitespace-only."
  6. Changed1 schema field changed
    • addedOutput schema / properties / found / items / properties / childrenTruncated
      Added value: +{
+  "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"
+}
  7. Changed4 schema fields changed
    • changedInput schema / properties / codes / description
      Previous value: -"Codes to decode (1–50). Mixed systems are fine — each is detected independently."New value: +"Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product."
    • changedInput schema / properties / codes / items / description
      Previous value: -"A single code to decode, with or without dots."New value: +"A single code to decode (with or without dots), an RXCUI, or an NDC."
    • changedOutput schema / properties / found / items / description
      Previous value: -"A decoded code, optionally with its parent and immediate children."New value: +"A decoded code, optionally with its parent/children and resolution source."
    • addedOutput schema / properties / found / items / properties / source
      Added value: +{
+  "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"
+}
  8. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses rich behavioral traits beyond the read-only/idempotent annotations: partial success with found/notFound and per-code reasons, malformed NDC codes staying unresolved, cross-system collision handling via alsoInSystems, hierarchy attachment with childrenTruncated, and system echoing for chaining. No contradiction with annotations; it enriches them with precise resolution semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded and the text flows logically from decoding to hierarchy to collision handling, with every sentence adding substantive information. However, the long multi-clause, comma-packed sentences require careful parsing, so the efficient density sacrifices some readability and structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With full parameter coverage, an output schema, and annotations, the description still adds all needed behavioral context: batch limits, partial-success semantics, malformed-code resolution, hierarchy truncation, and cross-system collision notes. Nothing an agent needs to invoke this tool correctly is missing or ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema already documents all three parameters at 100% coverage, the description adds operational meaning: codes can be mixed and independently detected, NDC formats are enumerated, forcing the system parameter skips NDC decode, and includeHierarchy attaches parent/children with a truncation flag. This materially improves an agent's ability to choose correct parameter values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Decode') and names the resource (US medical codes) plus the exact systems covered, including the NDC offline decoding edge case. It distinguishes itself from sibling tools by explicitly referencing medcode_browse_hierarchy/medcode_map_codes for hierarchy walking and a billability check, so an agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent to omit the system parameter for auto-detection and to pass it only for genuinely ambiguous values. It also names alternatives for walking a full hierarchy (medcode_browse_hierarchy or medcode_map_codes) and for chaining into a billability check, providing clear when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All medical-codes-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources