# KeepMD EOB Decoder — MCP server

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that helps an AI assistant read a
medical **Explanation of Benefits (EOB)**, Medicare Summary Notice or itemized bill. It is the same job the
[KeepMD EOB Decoder browser extensions](https://keepmd.org/eob-decoder/) do, exposed to Claude, ChatGPT,
Cursor and any other MCP client.

**Endpoint:** `https://mcp.keepmd.org/eob` (Streamable HTTP, no authentication)
**Documentation:** https://keepmd.org/eob-decoder/mcp/
**Publisher:** KeepMD (VertexMD, Inc.) · support@keepmd.org

## What it does

| Tool | Purpose |
| --- | --- |
| `lookup_codes` | Official descriptors for ICD-10-CM diagnosis codes, HCPCS Level II service/supply/drug codes and HCPCS modifiers, with chapter, plain-language notes and licensing notices for CPT, dental, NDC and X12 remark codes (recognized, not described). Up to 50 codes per call. |
| `search_codes` | Find ICD-10-CM or HCPCS Level II codes from words in a description, or by code prefix. |
| `explain_insurance_term` | ~115 insurance and billing terms (allowed amount, coinsurance, CO/PR group codes, No Surprises Act, observation status…) with examples and related terms. |
| `check_eob_math` | Recomputes one service line or claim total from the printed amounts and flags balance billing, mismatched totals and impossible cost sharing. |
| `get_eob_reading_guide` | Step-by-step guide to reading an EOB, disputing a bill, or appealing a denial, with links to official consumer resources. |

Plus the `decode_eob` prompt and two resources (`keepmd://eob-decoder/glossary`, `keepmd://eob-decoder/manifest`).

Every tool carries `readOnlyHint: true` and `openWorldHint: false`. Every clinical or financial payload carries a
`disclaimer` field: general billing and coding reference, not medical, legal or financial advice.

## Privacy

The server has no storage and no accounts. Tools accept **codes, terms and dollar amounts only**; no schema takes a
name, date of birth, member ID, claim number or statement text. Tool arguments are never logged. Full policy:
https://keepmd.org/privacy/eob-decoder-mcp/.

## Data

| Set | Release | License |
| --- | --- | --- |
| ICD-10-CM | FY2027 (effective 2026-10-01), NCHS/CMS | Public domain |
| HCPCS Level II | October 2026 quarterly file, CMS | Public domain (CDT D-codes dropped) |
| Glossary, reading guide, plain-language notes | KeepMD-authored | MIT |

CPT (AMA), CDT (ADA) and CARC/RARC (X12) descriptors are licensed and are **not** included. See `NOTICE.md`.
Exact versions and file hashes: `public/data/MANIFEST.json`.

## Use it

**Claude** (claude.ai → Settings → Connectors → Add custom connector): `https://mcp.keepmd.org/eob`
**Claude Code:** `claude mcp add --transport http keepmd-eob-decoder https://mcp.keepmd.org/eob`
**Cursor / VS Code / other clients:**

```json
{ "mcpServers": { "keepmd-eob-decoder": { "type": "http", "url": "https://mcp.keepmd.org/eob" } } }
```

**ChatGPT:** install from the app directory once listed (see `chatgpt/`).

Try: *"What do Z00.00, 99213 and J0696 mean on this EOB?"* · *"Explain allowed amount versus billed amount."* ·
*"Billed 1,200, allowed 650, deductible 500, 20% coinsurance. Is my 630 patient responsibility right?"*

## Run it yourself

```bash
npm install --legacy-peer-deps
npm run data:refresh      # downloads the CMS/NCHS releases and rebuilds public/data
npm test && npm run typecheck
npm run dev               # http://localhost:8787/eob
```

Built on `@modelcontextprotocol/server` (`createMcpHandler`, stateless Streamable HTTP) and Cloudflare Workers
with Static Assets for the code sets. Layout, release and data-refresh steps: `CONTRIBUTING.md`, `docs/DEPLOY.md`.
Directory submissions (Anthropic, OpenAI, MCP Registry and others): `docs/SUBMISSIONS.md`.

## License

MIT for code and KeepMD-authored content. Government data sources are public domain; see `NOTICE.md`.