Skip to main content
Glama
Sign In

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

NameRequiredDescriptionDefault

No arguments

Output 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. Changed1 schema field changed
    • changedOutput schema / properties / systems / items / properties / releaseId / description
      Previous value: -"Release/version identifier baked into this build, e.g. \"ICD-10-CM FY2026\"."New value: +"Release/version identifier baked into this build, e.g. \"ICD-10-CM FY2027\"."
  2. 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."
  3. 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"
+]
  4. 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"
-]
  5. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, and the description reinforces this usefully by explaining the corpus is offline and baked in at package-build time, so the call reflects the running server exactly. It also adds a real scope caveat (ICD-10-CM/PCS are US clinical modifications, not ICD-10/ICD-11 base) that annotations cannot convey.

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 first clause is front-loaded with what is returned, followed by the usage trigger and the scoping caveat. It is slightly dense and repetitive ('release identifiers' then 'with each source's version'), but every sentence carries information.

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, return-value detail is not required, and the description covers purpose, precondition, offline/static nature, and terminology caveats. An agent has everything needed to decide to call it and interpret the result.

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, so there is no parameter semantics to document and the baseline of 4 applies. Nothing in the description misleads about inputs.

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 (list) and resource (bundled US medical code systems) plus exactly what is returned: release identifiers, effective dates, code counts, and RxClass source versions. It is clearly distinguished from siblings that decode, search, or crosswalk, which it names.

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?

Gives a concrete usage trigger: call this to confirm which fiscal-year/release is active before acting on any decode, search, or crosswalk result. It does not explicitly say when not to use it, but the precondition framing makes the intended context unambiguous.

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