Skip to main content
Glama

medical-codes-mcp-server

by io.github.cyanheads

medical-codes-mcp-server

medcode_map_codes
Read-onlyIdempotent

Crosswalk a US medical code or drug across systems and within a hierarchy. Hierarchy directions: parents and children walk a code's prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full ancestor or descendant path (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent). A resolvable source with no edge in the requested direction is a successful empty result with a notice, not an error. A source code string that also exists in another bundled system carries alsoInSystems naming it, since only the resolved system's hierarchy was walked. Drug directions (RxNorm): name_to_rxcui (drug name → RXCUI), ndc_to_rxcui and rxcui_to_ndc (NDC ↔ RXCUI; NDCs accepted 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; ndc_to_rxcui names the product it decoded to), rxcui_to_ingredients and rxcui_to_brands (RXCUI → ingredient/brand RXCUIs, each with the target's RxNorm name and its conceptType — read that before counting a combination product's ingredients). Every result carries source provenance (which system or edge answered) so a chained call (e.g. into openfda with a resolved NDC) uses the right identifier. The children, name_to_rxcui, and rxcui_to_ndc directions can return large sets and paginate: a nextCursor in the response is passed back as cursor (with an optional limit page size) to walk the full set; the point directions ignore both.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fromYesThe source value: a code (for parents/children), a drug name, an NDC, or an RXCUI. Must not be blank or whitespace-only.
limitNoMax results per page for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions.
cursorNoOpaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui, rxcui_to_ndc). Omit for the first page.
systemNoFor parents/children, force the source code into this system. Omit to auto-detect.
directionYesWhat to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoPaginated directions only: the page size that was applied.
fromNoThe source value, echoed back.
hitsNoCrosswalk results, each tagged with the edge that produced it.
errorNoPresent when the call failed. Absent on success.
shownNoPaginated directions only: number of hits returned on this page.
noticeNoGuidance whenever a resolvable source returns no hits, naming which of the two causes applies: it has no edge in the requested direction (a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent), or the `cursor` starts past the last page of a direction that does have results.
directionNoThe mapping direction that was applied.
truncatedNoPaginated directions (children, name_to_rxcui, rxcui_to_ndc) only: true when more results exist beyond this page.
nextCursorNoPaginated directions only: opaque token to pass back as `cursor` for the next page. Present only when more results exist beyond this page.
alsoInSystemsNoOther bundled systems holding the same `from` code string, present only when there is at least one (hierarchy directions only — a drug name, NDC, or RXCUI is not system-scoped). The hits above were walked in `resolvedSystem` alone; the code is a DIFFERENT code with a different hierarchy 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 walk it there.
resolvedSystemNoThe system the source resolved in, or null when not system-scoped.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description is consistent with them (a crosswalk is read-only and idempotent). Beyond annotations, the description discloses substantial behavior: a resolvable source with no edge is a successful empty result with a notice (not an error), alsoInSystems for codes existing in multiple systems, source provenance on every result, the depth-1 hierarchy semantics, and the caveat to read conceptType before counting a combination product's ingredients. These add real value the annotations could not convey.

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 and nearly every sentence carries necessary behavioral content for a tool of this complexity (7 directions, pagination, multiple systems). However, it is delivered as one dense ~300-word paragraph with no structural breaks — no bullets, no per-direction sections — which makes it hard for an agent to scan. The information density justifies the length, but the wall-of-text format is a readability weakness.

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 5-parameter tool with 7 direction enums, pagination, and an output schema, the description is exceptionally complete: it covers direction semantics, error behavior, pagination mechanics, provenance, the combination-product caveat, and system override. Since an output schema exists, return-value explanation is unnecessary. There is no meaningful operational detail an agent would need that is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds considerable meaning beyond the schema: it elaborates each direction's semantics (depth-1 vs iterative, the RxNorm crosswalk behaviors, ndc_to_rxcui naming the decoded product), explains the cursor/nextCursor mechanism and which directions paginate, clarifies that point directions ignore limit/cursor, and explains system auto-detection vs forced resolution. This is far more than the schema strings alone provide.

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?

Opens with a specific verb+resource: 'Crosswalk a US medical code or drug across systems and within a hierarchy.' It names the exact operation (mapping between coding systems and hierarchy directions) and the resource scope, and the direction enums make the behavior concrete. It is clearly distinct from siblings like medcode_browse_hierarchy (browse), medcode_check_code (check), and medcode_search_codes (search) — this is the crosswalk tool, not a lookup, check, or search tool.

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?

Provides rich context on how to use each direction: iterative calls for full ancestor/descendant paths, empty-result semantics, pagination via nextCursor/cursor, and system override. It explains usage well, but it never names sibling tools or gives explicit exclusions ('use X instead when...'), so the when-not-to-use guidance is absent even though the how-to-use guidance is thorough.

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