medical-codes-mcp-server
Server Details
Offline US medical code lookup and crosswalk — ICD-10-CM, ICD-10-PCS, HCPCS Level II. Keyless.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.7/5 across 6 of 6 tools scored.
Each tool has a clearly distinct purpose: browsing hierarchy, validating codes, decoding descriptions, listing systems, crosswalking, and searching. No overlap in functionality.
All tools follow a consistent 'medcode_verb_noun' pattern (e.g., browse_hierarchy, check_code, get_code). This makes the set predictable and easy to navigate.
With 6 tools, the set is well-scoped for the domain of medical code reference. Each tool serves a distinct need without being excessive or insufficient.
The tool surface covers all essential operations for a read-only medical code server: browsing, validation, description lookup, system listing, crosswalking, and search. No obvious gaps.
Available Tools
6 toolsmedcode_browse_hierarchymedical-codes-mcp-serverARead-onlyIdempotentInspect
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), so browsing returns the valid values for the next character position, not prefix children. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | 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. | |
| limit | No | Max entries to return. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. | |
| system | Yes | The code system to browse. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | Yes | The limit that was applied. |
| axes | Yes | Valid next-position axis values for a partial PCS code. Empty when kind is "codes". |
| kind | Yes | "codes" for prefix-hierarchy children (ICD-10-CM/HCPCS); "axes" for ICD-10-PCS axis values. |
| codes | Yes | Child codes under the requested node or top level. Empty when kind is "axes". |
| shown | Yes | Number of entries returned (codes or axes). |
| notice | No | Guidance when a node has no children/axes — suggests the top level or a valid node. |
| truncated | Yes | True when the returned list was capped at the limit. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds substantial behavioral context: the prefix hierarchy for ICD-10-CM/HCPCS vs. axis-based traversal for ICD-10-PCS, what happens when node is omitted vs. provided, and that browsing returns immediate children or axis values. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 4-5 sentences with no filler. It front-loads the core purpose, then logically explains parameter behavior, system-specific differences, and use case. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, multiple code systems with different traversal rules, output schema present), the description covers all essential aspects: usage context, parameter behavior per system, and intended use case. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond schema descriptions. It explains how the node parameter behaves differently per system (prefix vs. axis), the default limit (MEDCODE_MAX_RESULTS=50), and provides context for each system enum value. This is exemplary value-add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Walk a US medical code system's hierarchy') and immediately distinguishes from search tools by noting it is for 'discovery without a search term.' It clearly explains behavior with and without a node and how different systems (ICD-10-CM, HCPCS, ICD-10-PCS) are handled, making it distinct from sibling tools like medcode_search_codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool ('for discovery without a search term' and 'orient in an unfamiliar system or enumerate a category's specific codes'). It does not explicitly list alternative tools or warn against misuse, but it provides clear context implying that search is for when a term is known. Slightly lacking in explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
medcode_check_codemedical-codes-mcp-serverARead-onlyIdempotentInspect
Validate whether a US medical code exists, is current, and is billable in the active bundled release. Returns a discriminated status — valid_billable, valid_not_billable, valid_header, or terminated — with a whyNot explaining non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code"). This is the detail a coder needs before submitting a claim. Auto-detects the system from the code's shape; pass an explicit system to disambiguate. A non-billable or terminated code is a successful result with a whyNot, not an error — only a code that exists in no bundled system raises unknown_code.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code to validate, with or without dots. | |
| system | No | Force the lookup into this system. Omit to auto-detect from the code's shape. |
Output Schema
| Name | Required | Description |
|---|---|---|
| code | Yes | The code in display form (ICD-10-CM carries the dot). |
| status | Yes | Validity status. valid_billable = submit as-is; valid_header/valid_not_billable = needs a more specific code; terminated = retired. |
| system | Yes | The system the code was resolved in, echoed for chaining. |
| whyNot | Yes | Explanation for non-billable/terminated statuses, or null when valid_billable. |
| billable | Yes | True only when status is valid_billable. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnly and idempotent hints. Description adds detailed behavior: discriminated status values, whyNot explanations, and that unknown_codes raise errors. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph but front-loads the core purpose. It could be slightly more structured (e.g., bullet points), but each sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 params and an output schema, the description covers all necessary context: purpose, behavior, interpretation of results, and parameter usage. Output schema handles detailed return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in schema (100% coverage). Description adds guidance on auto-detection vs explicit system, which adds value beyond the schema's static description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it validates whether a US medical code exists, is current, and is billable. It distinguishes from siblings (browse, get, list, map, search) by focusing on billing validation and specific statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains auto-detection of system from code shape and when to use explicit system parameter. Also clarifies that non-billable/terminated results are successful, not errors, guiding correct interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
medcode_get_codemedical-codes-mcp-serverARead-onlyIdempotentInspect
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 — when bundled — RxNorm (drugs). 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. The resolved system is echoed on every result for chaining into medcode_map_codes or a billability check.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | Codes to decode (1–50). Mixed systems are fine — each is detected independently. | |
| system | No | Force every code to be looked up in this system. Omit to auto-detect per code. | |
| includeHierarchy | No | When true, attach each found code's parent and immediate children. |
Output Schema
| Name | Required | Description |
|---|---|---|
| found | Yes | Successfully decoded codes, in request order. |
| notFound | Yes | Codes that did not resolve, with per-code reasons. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), the description discloses partial success behavior (found vs notFound with per-code reasons) and that the resolved system is echoed, which is valuable for agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single well-structured paragraph with no wasted words, but could be slightly shorter given that some information (like the list of systems) is already in the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters, behavior on partial success, output structure (found/notFound), and chaining hints. With output schema present, no further details are needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds extra meaning: auto-detection based on code shape, condition for explicit system use, and effect of includeHierarchy. These details go beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb 'decode' and resource 'US medical codes' across multiple systems, and distinguishes from siblings like medcode_search_codes by focusing on decoding codes to official descriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to pass an explicit system (only when ambiguous), mentions partial success, and suggests chaining to related tools (medcode_map_codes or billability check). Lacks explicit 'when not to use' but offers sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
medcode_list_systemsmedical-codes-mcp-serverARead-onlyIdempotentInspect
List the bundled US medical code systems with their release identifiers, effective dates, and code counts. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, and (when bundled) RxNorm month 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| systems | Yes | One entry per bundled code system, in canonical order. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable context: the corpus is offline and built at package-build time, and it clarifies that the report confirms the exact release. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences. The first sentence states the main purpose, and subsequent sentences add essential context. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output fields and the nature of the corpus. An output schema exists, so the description need not detail return values extensively. It covers the key behavioral context (offline, build-time, US clinical modifications) sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description compensates by detailing what the output contains (release identifiers, effective dates, code counts), which is more informative than just the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact action ('List the bundled US medical code systems') and the output fields (release identifiers, effective dates, code counts). It also distinguishes from sibling tools by explaining that this tool confirms active releases before performing decode/search/crosswalk operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'before acting on any decode, search, or crosswalk result.' It provides context about the offline nature and build-time construction, helping the agent understand that this is a prerequisite check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
medcode_map_codesmedical-codes-mcp-serverARead-onlyIdempotentInspect
Crosswalk a US medical code or drug across systems and within a hierarchy. Hierarchy directions (available now): parents and children walk a code's prefix hierarchy (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent). Drug directions (RxNorm): name_to_rxcui, ndc_to_rxcui, rxcui_to_ndc, rxcui_to_ingredients, rxcui_to_brands — these return an error until RxNorm is bundled in a later release. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | The source value: a code (for parents/children), a drug name, an NDC, or an RXCUI. | |
| system | No | For parents/children, force the source code into this system. Omit to auto-detect. | |
| direction | Yes | What to map to. parents/children walk the code hierarchy; the rxcui/ndc/name directions are RxNorm drug crosswalks (phase 2). |
Output Schema
| Name | Required | Description |
|---|---|---|
| from | Yes | The source value, echoed back. |
| hits | Yes | Crosswalk results, each tagged with the edge that produced it. |
| direction | Yes | The mapping direction that was applied. |
| resolvedSystem | Yes | The system the source resolved in, or null when not system-scoped. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent. Description adds that drug directions return error until later release, ICD-10-PCS codes lack prefix parent, and results include source provenance. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive, with clear separation between hierarchy and drug sections. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, description covers parameters, limitations, provenance, and chaining context. Complete for a mapping tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant meaning: explains the from field types, system auto-detection, and detailed direction options including future plans. Enhances understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool crosswalks medical codes/drugs across systems and hierarchies. Distinguishes from siblings (e.g., browse_hierarchy, search_codes) by focusing on mapping rather than browsing or searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use hierarchy directions vs. drug directions, including a note that drug directions are not yet available. Provides context for chaining with other tools (e.g., openfda). Does not explicitly list when not to use or alternative tools, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
medcode_search_codesmedical-codes-mcp-serverARead-onlyIdempotentInspect
Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear (prefix-matched), so "diabetic neuropathy" returns codes mentioning both. Filter by system (ICD10CM/ICD10PCS/HCPCS/RXNORM), billableOnly to exclude headers/categories, and chapter. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, and disclose truncation when the result hits the cap.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max codes to return. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200. | |
| query | Yes | Clinical description to match, e.g. "type 2 diabetes with neuropathy". | |
| system | No | Restrict results to one system. Omit to search all bundled systems. | |
| chapter | No | Restrict to a chapter/range bucket (the value from a code's `chapter` field). | |
| billableOnly | No | When true, return only billable leaf codes (exclude headers/categories). |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | Yes | The limit that was applied. |
| codes | Yes | Matching codes, ranked by full-text relevance. |
| shown | Yes | Number of codes returned. |
| notice | No | Guidance when nothing matched — echoes the query and suggests how to broaden. |
| truncated | Yes | True when results were capped at the limit. |
| appliedFilters | Yes | Filters the server applied to the search. |
| effectiveQuery | Yes | The query as the server parsed it for matching. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds beyond these: it explains full-text search behavior, prefix matching, resolved system per row in results, and truncation disclosure. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 4 sentences, with the most important information (purpose and matching logic) in the first sentence. Every sentence adds essential detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary behavioral aspects for a search tool with good annotations and a full output schema. It explains result features (resolved system, truncation) and filter options. No gaps remain given the rich supporting artifacts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds context for each parameter: it explains the matching logic for query, the available systems for system, the effect of billableOnly, the chapter filter, and the limit default and ceiling. This adds meaningful semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding US medical codes via full-text search over a bundled index. It specifies the matching requirement (every term must appear, prefix-matched) and contrasts with the sibling tool medcode_get_code, which is the reverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: when you have a clinical description and need the code. It also names the sibling tool medcode_get_code as the alternative for reverse lookup. However, it does not explicitly list all sibling tools or detail when not to use this tool, so it loses 1 point for completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!