medical-codes-mcp-server

Browse Code Hierarchy

medcode_browse_hierarchy

Read-onlyIdempotent

Walk a US medical code system's hierarchy for discovery without a search term. With no node, returns the top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values). With a node, returns its immediate children. ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — each of its 7 characters is an independent axis (section, body system, root operation, body part, approach, device, qualifier), but only the top-level Section axis is browsable (omit node): positions 2–7 are context-dependent on the preceding axis path and are not enumerable from a flat partial code, so list the complete codes in a three-character ICD-10-PCS table row with medcode_map_codes (direction children) instead. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes. A large child set paginates: when the response carries a nextCursor, pass it back as cursor to fetch the next page.

Input Schema

Name	Required	Description
`node`	No	A node to expand — or omit / pass an empty string for the top level. For ICD-10-CM/HCPCS, a code whose children to list; ICD-10-PCS supports only top-level Section browsing. Must not be blank or whitespace-only when provided.
`limit`	No	Max entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200.
`cursor`	No	Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.
`system`	Yes	The code system to browse.

Output Schema

Name	Required	Description
`cap`	No	The page size that was applied.
`axes`	No	The top-level ICD-10-PCS Section axis values (only the Section axis is enumerable). Empty when kind is "codes".
`kind`	No	"codes" for prefix-hierarchy children (ICD-10-CM/HCPCS); "axes" for ICD-10-PCS axis values.
`codes`	No	Child codes under the requested node or top level. Empty when kind is "axes".
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of entries returned on this page (codes or axes).
`notice`	No	Guidance when a node has no children/axes — suggests the top level or a valid node.
`truncated`	No	True when more entries exist beyond this page.
`nextCursor`	No	Opaque token to pass back as `cursor` for the next page. Present only when more entries exist beyond this page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 25, 2026

changedOutput schema / properties / codes / items / properties / billable / description

Previous value: -"True when the code is a billable leaf. Null when the system has no billing concept."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."

Changed2 schema fields changedSep 24, 2026

changedOutput schema / properties / codes / items / properties / billable / description

Previous value: -"True when the code is a billable leaf."New value: +"True when the code is a billable leaf. Null when the system has no billing concept."

changedOutput schema / properties / codes / items / properties / billable / type
```
Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
```

Changed6 schema fields changedSep 19, 2026
- removedOutput schema / properties / codes / items / properties / chapter / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / codes / items / properties / chapter / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / codes / items / properties / description / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / codes / items / properties / description / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / codes / items / properties / shortDescription / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / codes / items / properties / shortDescription / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

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": [
+      "kind",
+      "codes",
+      "axes",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "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: `unknown_node`: The node does not exist in the system — for ICD-10-PCS, also when it uses a character outside the axis alphabet or begins no bundled code. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_node"
+          ],
+          "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: -[
-  "kind",
-  "codes",
-  "axes",
-  "truncated",
-  "shown",
-  "cap"
-]

Changed3 schema fields changedJul 13, 2026

addedInput schema / properties / node / anyOf

Added value: +[
+  {
+    "const": "",
+    "type": "string"
+  },
+  {
+    "description": "A code whose children to list (ICD-10-CM/HCPCS). ICD-10-PCS supports only top-level Section browsing — a partial PCS code does not expand to next-position axis values.",
+    "minLength": 1,
+    "type": "string"
+  }
+]

changedInput schema / properties / node / description

Previous value: -"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. ICD-10-PCS supports only top-level Section browsing (omit `node`) — a partial PCS code does not expand to next-position axis values. Omit for the top level."New value: +"A node to expand — or omit / pass an empty string for the top level. For ICD-10-CM/HCPCS, a code whose children to list; ICD-10-PCS supports only top-level Section browsing. Must not be blank or whitespace-only when provided."

removedInput schema / properties / node / type
```
Removed value: -"string"
```

Changed6 schema fields changedJul 13, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.",
+  "type": "string"
+}

changedInput schema / properties / limit / description

Previous value: -"Max entries to return. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200."New value: +"Max entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200."

changedOutput schema / properties / cap / description

Previous value: -"The limit that was applied."New value: +"The page size that was applied."

addedOutput schema / properties / nextCursor

Added value: +{
+  "description": "Opaque token to pass back as `cursor` for the next page. Present only when more entries exist beyond this page.",
+  "type": "string"
+}

changedOutput schema / properties / shown / description

Previous value: -"Number of entries returned (codes or axes)."New value: +"Number of entries returned on this page (codes or axes)."

changedOutput schema / properties / truncated / description

Previous value: -"True when the returned list was capped at the limit."New value: +"True when more entries exist beyond this page."

Changed2 schema fields changedJun 20, 2026

changedInput schema / properties / node / description

Previous value: -"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. For ICD-10-PCS, a partial code whose next-position axis values to list. Omit for the top level."New value: +"A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. ICD-10-PCS supports only top-level Section browsing (omit `node`) — a partial PCS code does not expand to next-position axis values. Omit for the top level."

changedOutput schema / properties / axes / description

Previous value: -"Valid next-position axis values for a partial PCS code. Empty when kind is \"codes\"."New value: +"The top-level ICD-10-PCS Section axis values (only the Section axis is enumerable). Empty when kind is \"codes\"."

First observedJun 16, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover read-only/idempotent/closed-world, and the description adds real value on top: the prefix vs axis-based parent relationship per system, the PCS top-level-only constraint and why, and the nextCursor pagination loop. It stops short of stating result shape or depth limits, but the safety and paging profile is well disclosed.

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?

Front-loaded with the core behavior and the no-node/node split before the system-specific rules, so the agent can stop reading early. Slight cost: the PCS restriction is restated in both the description and the `node` schema, making the paragraph denser than strictly needed.

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?

For a four-parameter, single-required browse tool with an output schema and full annotation coverage, nothing an agent needs is missing: entry points, child expansion, per-system hierarchy semantics, the PCS fallback, and pagination are all covered.

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 100%, so baseline is 3; the description earns more by explaining what a `node` actually means in each system (prefix parent vs non-enumerable axes) and how `cursor` is fed back from `nextCursor`. It does not add anything for `limit`, which the schema already documents fully.

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 and resource (walk a code system's hierarchy) and immediately scopes it as discovery without a search term, which separates it from medcode_search_codes. It also names the exact return shape per system (ICD-10-CM categories, HCPCS ranges, PCS first-axis values).

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?

Explicitly says when to use it (orient in an unfamiliar system, enumerate a category's specific codes) and when not to, routing the PCS positions 2–7 case to medcode_map_codes with direction children. That is a concrete alternative plus the condition that selects it.

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 tools Inspect

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.