Skip to main content
Glama
Sign In

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, and a code written in ICD-10-CM dotted form (A01.00) resolves to ICD-10-CM; 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. Each reply holds structuredContent and the text to 24,000 bytes apiece: codes are decoded in request order, and once one has resolved, a code that would carry the reply past that budget is returned unprocessed in deferred, as sent, with every code after it — re-call with codes set to deferred and the same system and includeHierarchy until no deferred comes back. Three kinds of code are never deferred and can carry a reply past the budget: the first code that resolves, returned whole; the codes before it; and the unresolved codes after the last one that resolves, so a re-call always holds a code that resolves. Only a batch where nothing resolves fails: with ambiguous_system and candidateSystems when every code exists in more than one bundled system, otherwise with no_codes_found. 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_map_codes, or medcode_browse_hierarchy outside ICD-10-PCS); an ICD-10-PCS table row's children are the complete codes that begin with it. 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 dotted all-digit value in ICD-9-CM form (250.00) is never read as an RXCUI and is named as ICD-9-CM, which is not bundled; an ICD-10-PCS section value from medcode_browse_hierarchy (0) looked up under system ICD10PCS is named as a section, not a code; 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

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

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
foundNoSuccessfully decoded codes, in request order.
deferredNoInput codes not processed because the reply reached its byte budget, in request order and as sent. Re-call with these as codes and the same system and includeHierarchy, until no deferred comes back. Absent when every code was processed.
notFoundNoCodes that did not resolve, with per-code reasons.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedOutput schema / properties / deferred
      Added value: +{
+  "description": "Input codes not processed because the reply reached its byte budget, in request order and as sent. Re-call with these as codes and the same system and includeHierarchy, until no deferred comes back. Absent when every code was processed.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • 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 resolved — in any bundled system, or in the explicit `system` when one is given. The message names each code another bundled system holds and each code present in more than one system, with those systems. `ambiguous_system`: Every requested code is present in more than one bundled system and no `system` was given; `candidateSystems` lists the union of those systems. 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 names each code another bundled system holds and each code present in more than one system, with those systems, and each ICD-10-PCS section value, bare integer, value in ICD-9-CM form, and NDC among the misses. `ambiguous_system`: Every requested code is present in more than one bundled system and no `system` was given; `candidateSystems` lists the union of those systems. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / found / items / properties / children / description
      Previous value: -"Immediate child codes (present only when includeHierarchy is true)."New value: +"Immediate child codes (present only when includeHierarchy is true). For an ICD-10-PCS table row, the complete codes that begin with it."
    • changedOutput schema / properties / found / items / properties / children / items / properties / header / description
      Previous value: -"True when the code is a non-billable category/header (ICD-10-CM) rather than a leaf code."New value: +"True when the code is a non-billable header with codes below it — an ICD-10-CM category, a HCPCS range bucket, or a three-character ICD-10-PCS table row — rather than a leaf code."
    • changedOutput schema / properties / found / items / properties / childrenTruncated / description
      Previous value: -"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."New value: +"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_map_codes (children) for this code, passing its `system`, or medcode_browse_hierarchy outside ICD-10-PCS."
    • changedOutput schema / properties / found / items / properties / header / description
      Previous value: -"True when the code is a non-billable category/header (ICD-10-CM) rather than a leaf code."New value: +"True when the code is a non-billable header with codes below it — an ICD-10-CM category, a HCPCS range bucket, or a three-character ICD-10-PCS table row — rather than a leaf code."
    • changedOutput schema / properties / found / items / properties / parent / description
      Previous value: -"Immediate parent code (present only when includeHierarchy is true). Null at a root."New value: +"Immediate parent code, always one medcode_get_code decodes (present only when includeHierarchy is true): an ICD-10-CM code padded with the placeholder X names the nearest code above the padding (`S82.66XA` → `S82.66`), and a complete ICD-10-PCS code names its three-character table row (`0DTJ4ZZ` → `0DT`). Null at a root — an ICD-10-CM category, a HCPCS range bucket, an ICD-10-PCS table row — and for RxNorm."
    • changedOutput schema / properties / notFound / items / properties / reason / description
      Previous 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)."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, and for a dotted all-digit value in ICD-9-CM form such as \"250.00\", with a note that ICD-9-CM is not bundled — absent from the explicit `system` while another bundled system holds it, which is named, an ICD-10-PCS section value looked up as a code under system ICD10PCS, which is named as that section, 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. Changed4 schema fields changed
    • 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 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."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 names each code another bundled system holds and each code present in more than one system, with those systems. `ambiguous_system`: Every requested code is present in more than one bundled system and no `system` was given; `candidateSystems` lists the union of those systems. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "no_codes_found"
-]New value: +[
+  "no_codes_found",
+  "ambiguous_system"
+]
    • 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. Null when the system has no billing concept (RxNorm)."New value: +"True when the code is a billable leaf. False for headers/categories, non-billable codes, and HCPCS codes whose last valid date has passed. Null when the system has no billing concept (RxNorm)."
    • 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. Null when the system has no billing concept (RxNorm)."New value: +"True when the code is a billable leaf. False for headers/categories, non-billable codes, and HCPCS codes whose last valid date has passed. Null when the system has no billing concept (RxNorm)."
  3. 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)."
  4. 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"
+]
  5. 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"
-]
  6. 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)."
  7. 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."
  8. 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"
+}
  9. 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"
+}
  10. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations only say read-only, idempotent, closed-world; the description adds a great deal beyond that — partial-success semantics with found/notFound per-code reasons, the 24,000-byte budget and deferral protocol with its three never-deferred exceptions, and the exact failure modes (ambiguous_system with candidateSystems, no_codes_found). The deferral rules are dense enough that an agent may still mis-model edge cases on first read, which keeps it off a 5.

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

Conciseness3/5

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

The purpose is front-loaded in the first clause, but the body is a single ~350-word paragraph with long em-dash-chained clauses that bury the deferral protocol mid-stream. Nearly every sentence carries needed information, but the lack of structural break-out for the budget/deferral rules hurts scannability.

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

Completeness4/5

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

An output schema exists and annotations cover safety, yet the tool is genuinely complex (batch, mixed systems, partial success, deferral, ambiguity); the description covers the error contract and chaining of the echoed `system`. Almost nothing an agent needs is missing, though the deferral rules would benefit from tighter organization.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3; the description earns an extra point by adding value-level rules the schema does not state — which NDC segment widths are valid (4-4-2, 5-3-2, 5-4-1, 5-4-2) versus malformed, dotted ICD-10-CM form resolving to ICD-10-CM, and that an ICD-10-PCS table row's children are the complete codes beginning with it.

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?

States a specific verb (decode) and resource (US medical codes) with the exact code systems named (ICD-10-CM, ICD-10-PCS, HCPCS Level II, RxNorm, NDC), and distinguishes itself from siblings by pointing at medcode_map_codes and medcode_browse_hierarchy for hierarchy walks and at billability checks downstream.

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?

Explicit routing rules: pass `system` only when a value is genuinely ambiguous, otherwise rely on auto-detect; re-call with `deferred` codes and the same `system`/`includeHierarchy` until none come back; use medcode_map_codes or medcode_browse_hierarchy when childrenTruncated. It even names what is out of scope (CPT / HCPCS Level I, ICD-9-CM).

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