Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads

medical-codes-mcp-server

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 medcode_map_codes or a billability check; 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. 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. Dates show when Glama detected each change.

  1. 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"
-]
  2. 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)."
  3. 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."
  4. 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"
+}
  5. 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"
+}
  6. First observed

TDQS

A5/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=false), the description discloses critical runtime behavior: partial success with `found` and `notFound` fields and per-code reasons, malformed NDC handling, auto-detection, the `childrenTruncated` flag, and the `alsoInSystems` collision signal. It also explains the impact of `includeHierarchy` and how to walk the full set. This goes well beyond the annotations, giving an agent a precise mental model of the tool's behavior.

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

Conciseness5/5

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

The description is long but every sentence earns its place, covering the core action, NDC specifics, batch semantics, hierarchy option, collision handling, and chaining. It is front-loaded with the primary purpose, then branches into details. No redundant or filler language—each clause contributes to actionable understanding.

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?

Given the tool's complexity (multiple coding systems, NDC decoding, partial success, hierarchy, collisions) and the presence of an output schema, the description covers all necessary aspects: input constraints, optional parameters, edge cases, and secondary behavior. It even mentions the `alsoInSystems` field and the `childrenTruncated` flag, which are likely part of the output schema but are reinforced here. An agent can fully anticipate how to call the tool and interpret results without further inspection.

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?

Even though the schema has 100% coverage with descriptions for each parameter, the description adds meaningful detail: it specifies exact NDC segment formats (4-4-2, 5-3-2, 5-4-1, 5-4-2, and bare 10/11 digits), clarifies that the `codes` array accepts mixed systems, and explains that `system` is only for forced lookups. This adds semantic value beyond the schema, particularly around edge cases and expected input formats.

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 and resource: 'Decode one or more US medical codes to their official descriptions' across multiple named systems (ICD-10-CM, ICD-10-PCS, HCPCS, RxNorm). It distinguishes itself from siblings by covering decoding specifically, and further differentiates NDC decoding as a unique behavior. The description is clearly about a batch decoding tool, not a search, map, browse, or check tool.

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?

The description explicitly states when to pass the `system` parameter ('only when a value is genuinely ambiguous'), and directs users to alternatives for fuller hierarchy traversal ('walk the full set via medcode_browse_hierarchy or medcode_map_codes'). It also mentions chaining into medcode_map_codes or a billability check, providing actionable routing. This is clear, specific guidance that selects this tool over siblings.

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
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

Each tool serves a unique, non-overlapping function: browsing hierarchy, validating codes, decoding descriptions, listing systems, mapping between codes, and searching by clinical description. There is no ambiguity in selecting the right tool for a task.

Naming Consistency5/5

All tool names follow the 'medcode_' prefix with a clear verb_noun pattern: browse_hierarchy, check_code, get_code, list_systems, map_codes, search_codes. This is a perfectly consistent naming convention.

Tool Count5/5

With six tools, the server is well-scoped for its purpose of decoding, validating, searching, and crosswalking medical codes. Each tool covers a distinct essential capability, and the count feels appropriate for a focused domain.

Completeness5/5

The tool set covers the full read-only lifecycle: discovering codes (browse), searching (search), decoding (get), validating (check), crosswalking (map), and identifying release versions (list_systems). There are no obvious dead ends or missing operations for this domain.

Resources