# io.github.cyanheads/medical-codes-mcp-server (remote · medical-codes.caseyjhand.com)

Offline US medical code lookup and crosswalk — ICD-10-CM/PCS, HCPCS Level II, RxNorm. Keyless.

- Trust score: 68/100 (medium)
- Change this week: +6
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `medical-codes.caseyjhand.com`: 68/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes.md), [page](https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes)
- npm · `@cyanheads/medical-codes-mcp-server`: 35/100, [markdown](https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/cyanheads-medical-codes-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/cyanheads-medical-codes-mcp-server)

## Channel facts

- Endpoint: `https://medical-codes.caseyjhand.com/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.2.3`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 66/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 6 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC is configured correctly; the domain's records validate against the full chain to the root.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 61/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2144 tokens (~357/item across 6 items; 6 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http cyanheads-medical-codes-mcp-server https://medical-codes.caseyjhand.com/mcp
```

### Codex

```toml
[mcp_servers.cyanheads-medical-codes-mcp-server]
url = "https://medical-codes.caseyjhand.com/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-medical-codes-mcp-server": {
      "type": "remote",
      "url": "https://medical-codes.caseyjhand.com/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-medical-codes-mcp-server --url https://medical-codes.caseyjhand.com/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  cyanheads-medical-codes-mcp-server:
    url: "https://medical-codes.caseyjhand.com/mcp"
```

### Other

```json
{
  "mcpServers": {
    "cyanheads-medical-codes-mcp-server": {
      "type": "http",
      "url": "https://medical-codes.caseyjhand.com/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-01 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 66, +2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 64, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 64, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 63, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 62, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 62)

First indexed and scored.

## MCP tools (6)

### `medcode_get_code` (~334 tokens)

medical-codes-mcp-server

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 RxNorm (drugs, by RXCUI). Also decodes a National Drug Code (NDC) — hyphenated or 10/11-digit — directly to its RxNorm product offline, tagged `source: "NDC"`. 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 (with a `childrenTruncated` flag when a code has more children than the cap returns — walk the full set via medcode_browse_hierarchy or medcode_map_codes). The resolved `system` is echoed on every result for chaining into medcode_map_codes or a billability check.

Input parameters:

- `codes` (array, required): Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product.
- `includeHierarchy` (boolean): When true, attach each found code's parent and immediate children.
- `system` (string): Force every code to be looked up in this system. Omit to auto-detect per code.

Output parameters:

- `found` (array): Successfully decoded codes, in request order.
- `notFound` (array): Codes that did not resolve, with per-code reasons.

### `medcode_search_codes` (~363 tokens)

medical-codes-mcp-server

Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear — matched first as a token prefix, then as a substring so inflected and compound forms are also found (a "neuropathy" search surfaces "mononeuropathy"/"polyneuropathy" siblings too, not only a standalone "neuropathy" token). 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, rank exact prefix matches ahead of substring-only matches with a deterministic tie-break, and disclose truncation with a `nextCursor`: pass it back as `cursor` to page through the full ranked set.

Input parameters:

- `billableOnly` (boolean): When true, return only billable leaf codes (exclude headers/categories).
- `chapter` (string): Restrict to a chapter/range bucket (the value from a code's `chapter` field).
- `cursor` (string): Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of the same ranked result set. Omit for the first page.
- `limit` (integer): Max codes per page. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200.
- `query` (string, required): Clinical description to match, e.g. "type 2 diabetes with neuropathy". Must not be blank or whitespace-only.
- `system` (string): Restrict results to one system. Omit to search all bundled systems.

Output parameters:

- `appliedFilters` (object): Filters the server applied to the search.
- `cap` (number): The page size that was applied.
- `codes` (array): Matching codes, ranked by full-text relevance.
- `effectiveQuery` (string): The query as the server parsed it for matching.
- `nextCursor` (string): Opaque token to pass back as `cursor` for the next page. Present only when more matches exist beyond this page.
- `notice` (string): Guidance when nothing matched — echoes the query and suggests how to broaden.
- `shown` (number): Number of codes returned on this page.
- `truncated` (boolean): True when more matches exist beyond this page.

### `medcode_check_code` (~208 tokens)

medical-codes-mcp-server

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.

Input parameters:

- `code` (string, required): The code to validate, with or without dots. Must not be blank or whitespace-only.
- `system` (string): Force the lookup into this system. Omit to auto-detect from the code's shape.

Output parameters:

- `billable` (boolean): True only when status is valid_billable.
- `code` (string): The code in display form (ICD-10-CM carries the dot).
- `status` (string): Validity status. valid_billable = submit as-is; valid_header/valid_not_billable = needs a more specific code; terminated = retired.
- `system` (string): The system the code was resolved in, echoed for chaining.
- `whyNot`: Explanation for non-billable/terminated statuses, or null when valid_billable.

### `medcode_map_codes` (~501 tokens)

medical-codes-mcp-server

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 code with no edge in the requested direction is a successful empty result with a notice, not an error. Drug directions (RxNorm): `name_to_rxcui` (drug name → RXCUI), `ndc_to_rxcui` and `rxcui_to_ndc` (NDC ↔ RXCUI; NDCs accepted hyphenated or 10/11-digit), `rxcui_to_ingredients` and `rxcui_to_brands` (RXCUI → ingredient/brand RXCUIs). 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` and `name_to_rxcui` 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 parameters:

- `cursor` (string): Opaque continuation token from a previous response's `nextCursor`, for the paginated directions (children, name_to_rxcui). Omit for the first page.
- `direction` (string, required): What 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.
- `from` (string, required): The source value: a code (for parents/children), a drug name, an NDC, or an RXCUI. Must not be blank or whitespace-only.
- `limit` (integer): Max results per page for the paginated directions (children, name_to_rxcui). Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200. Ignored by the point directions.
- `system` (string): For parents/children, force the source code into this system. Omit to auto-detect.

Output parameters:

- `cap` (number): Paginated directions only: the page size that was applied.
- `direction` (string): The mapping direction that was applied.
- `from` (string): The source value, echoed back.
- `hits` (array): Crosswalk results, each tagged with the edge that produced it.
- `nextCursor` (string): Paginated directions only: opaque token to pass back as `cursor` for the next page. Present only when more results exist beyond this page.
- `notice` (string): Guidance when a resolvable code has no edge in the requested direction (e.g. a top-level code has no parent; a leaf has no children; ICD-10-PCS codes have no prefix parent).
- `resolvedSystem`: The system the source resolved in, or null when not system-scoped.
- `shown` (number): Paginated directions only: number of hits returned on this page.
- `truncated` (boolean): Paginated directions (children, name_to_rxcui) only: true when more results exist beyond this page.

### `medcode_browse_hierarchy` (~351 tokens)

medical-codes-mcp-server

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. 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 parameters:

- `cursor` (string): Opaque continuation token from a previous response's `nextCursor`, to fetch the next page of children/entries. Omit for the top of the list.
- `limit` (integer): Max entries per page. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200.
- `node`: 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 whit…
- `system` (string, required): The code system to browse.

Output parameters:

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

### `medcode_list_systems` (~124 tokens)

medical-codes-mcp-server

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 RxNorm normalized set 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.

Output parameters:

- `systems` (array): One entry per bundled code system, in canonical order.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 67
- 2026-08-01: 67
- 2026-07-31: 66
- 2026-07-30: 64
- 2026-07-29: 64
- 2026-07-28: 63
- 2026-07-27: 62
- 2026-07-26: 62

## Links

- Remote endpoint: https://medical-codes.caseyjhand.com/mcp
- Repository: https://github.com/cyanheads/medical-codes-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes/changelog.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-medical-codes-mcp-server/medical-codes