Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

List Code Systems

medcode_list_systems
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
systemsNoOne entry per bundled code system, in canonical order — the systems the `system` inputs of the other tools accept.
classLayerNoThe 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "systems"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "systems",
+      "classLayer"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / classLayer
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "classCount": {
+          "description": "RxClass class nodes bundled, including hierarchy nodes with no direct member.",
+          "type": "number"
+        },
+        "edgeCount": {
+          "description": "Drug–class edges bundled, across every source.",
+          "type": "number"
+        },
+        "sourceUrl": {
+          "description": "The RxClass API the layer was fetched from.",
+          "type": "string"
+        },
+        "sources": {
+          "description": "One entry per bundled RxClass source.",
+          "items": {
+            "additionalProperties": false,
+            "description": "Provenance for one bundled RxClass source.",
+            "properties": {
+              "classCount": {
+                "description": "Classes this source asserts at least one bundled edge to.",
+                "type": "number"
+              },
+              "edgeCount": {
+                "description": "Drug–class edges this source contributes.",
+                "type": "number"
+              },
+              "fetchedAt": {
+                "description": "ISO 8601 date the RxClass snapshot was fetched — how current the class edges are.",
+                "type": "string"
+              },
+              "source": {
+                "description": "The RxClass source, as class hits carry it in `source`: MEDRT, FDASPL, FMTSME, VA, RXNORM (DEA schedules), or CDC (CVX).",
+                "type": "string"
+              },
+              "version": {
+                "description": "The release RxClass reports for this source, or null when it publishes none.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "source",
+              "version",
+              "classCount",
+              "edgeCount",
+              "fetchedAt"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "classCount",
+        "edgeCount",
+        "sourceUrl",
+        "sources"
+      ],
+      "type": "object"
+    },
+    {
+      "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."
+}
    • changedOutput schema / properties / systems / description
      Previous value: -"One entry per bundled code system, in canonical order."New value: +"One entry per bundled code system, in canonical order — the systems the `system` inputs of the other tools accept."
    • changedOutput schema / properties / systems / items / properties / builtAt / description
      Previous value: -"ISO 8601 timestamp when this system was last baked."New value: +"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."
  2. Changed6 schema fields changed
    • removedOutput schema / properties / systems / items / properties / effectiveEnd / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / systems / items / properties / effectiveEnd / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / systems / items / properties / effectiveStart / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / systems / items / properties / effectiveStart / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / systems / items / properties / sourceUrl / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / systems / items / properties / sourceUrl / 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": [
+      "systems"
+    ]
+  },
+  {
+    "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.",
+          "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: -[
-  "systems"
-]
  4. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already provide readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: the corpus is offline, built at package-build time, and the call reports exactly which release is baked into the running server. It also clarifies the ICD-10-CM/PCS scope to prevent confusion with base ICD-10/ICD-11. No contradiction with annotations.

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?

Three sentences, each earning its place: the first states what is listed, the second states when to use the result, and the third adds the offline/build-time behavior and the ICD-10 scope clarification. It is dense but not bloated.

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 an output schema present, the description does not need to detail return values. It fully covers the tool's purpose, the systems involved, versioning semantics, offline behavior, and the relationship to sibling operations, so an agent has enough context to select and invoke it correctly.

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?

The tool takes zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The description instead usefully explains what the returned report contains, which is the relevant semantic content for a no-argument call.

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 uses a specific verb and resource: 'List the bundled US medical code systems' with their release identifiers, effective dates, and code counts, plus the RxClass layer. It also distinguishes this metadata/version-reporting tool from sibling decode/search/crosswalk tools by saying it confirms which releases are active before acting on those operations.

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

Usage Guidelines4/5

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

The description explicitly frames when to use this tool: 'before acting on any decode, search, or crosswalk result.' It gives clear contextual guidance for version verification, though it does not explicitly name alternative tools or state when not to use it beyond that implied scope.

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