# Medikode MCP Server

[![npm](https://img.shields.io/npm/v/@medikode/mcp-server)](https://www.npmjs.com/package/@medikode/mcp-server)
[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)

**Bring AI-powered medical coding into Claude, Cursor, and ChatGPT.**

The Medikode MCP Server exposes [Medikode.ai](https://medikode.ai)'s medical coding platform through the [Model Context Protocol](https://modelcontextprotocol.io). Coders, auditors, and revenue cycle teams can validate codes, QA charts, parse EOBs, and score risk adjustment directly from the AI assistant they already use — with every call authenticated, tracked, and billed through their Medikode account.

![Medikode dashboard](medikode-dashboard.png)

---

## Why this exists

Revenue cycle teams spend hours moving between EHRs, coding tools, and payer portals. LLM assistants are good at reading clinical notes but have no reliable source of truth for code validity, NCCI edits, or RAF weights. This server closes that gap: the assistant does the reasoning, and Medikode's platform supplies the validated, auditable answer.

## Tools

| Tool | What it does | Typical use |
|---|---|---|
| `validate_codes` | Checks CPT / ICD-10 codes against the clinical documentation | Pre-bill validation |
| `qa_chart` | Runs a coding quality-assurance review on a chart | Audit and coder feedback |
| `parse_eob` | Extracts structured data from insurance EOBs / remittances | Payment posting, denial analysis |
| `score_raf` | Calculates Risk Adjustment Factor (RAF) scores | Risk adjustment / HCC workflows |
| `multi_validate` | Combines code validation and RAF scoring in one call | End-to-end chart review |

## Quick start

**Requirements:** Node.js 24.7+ and a Medikode API key (get one at [medikode.ai](https://medikode.ai)).

```bash
npm install -g @medikode/mcp-server
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "medikode": {
      "command": "npx",
      "args": ["-y", "@medikode/mcp-server"],
      "env": {
        "MEDIKODE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor

Add the same block to Cursor's MCP settings (`~/.cursor/mcp.json`).

Restart the client, then ask something like:

> *"Validate CPT 99214 with ICD-10 E11.9 against this note…"*

## Architecture

```
AI assistant (Claude / Cursor / ChatGPT)
        │  MCP (stdio or WebSocket)
        ▼
Medikode MCP Server  ── API key auth · caching · request validation (Joi)
        │  HTTPS
        ▼
Medikode API  ── prod / sandbox routing
        │
        ▼
Coding engine · NCCI edits · RAF models · usage dashboard
```

- **Transports:** stdio for desktop clients; WebSocket for hosted and ChatGPT integrations
- **Environment routing:** separate production and sandbox API endpoints
- **Security:** API-key authentication, Helmet, configurable CORS, no PHI stored by the server
- **Observability:** health checks, structured logging, and per-call usage in the Medikode dashboard

## Configuration (self-hosted)

Copy `env.example` to `.env`:

| Variable | Purpose |
|---|---|
| `PORT` | Server port (default `3000`) |
| `NODE_ENV` | `production` or `development` |
| `PROD_API_SERVICE_URL` | Production Medikode API |
| `SANDBOX_API_SERVICE_URL` | Sandbox Medikode API |
| `BACKEND_SERVICE_URL` | Backend service URL |
| `ALLOWED_ORIGINS` | CORS allow-list |
| `LOG_LEVEL` | Logging verbosity |
| `HEALTH_CHECK_TIMEOUT` | Health-check timeout (ms) |

Docker:

```bash
docker compose up -d
```

## Development

```bash
git clone https://github.com/raelango/medikode-mcp-server.git
cd medikode-mcp-server
npm install
npm run dev
```

Tests cover unit behaviour, environment routing, WebSocket transport, MCP Inspector compatibility, and ChatGPT integration (`test-*.js`, `test-chatgpt-integration.py`).

See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).

## Related

- [medikode-agents](https://github.com/raelango/medikode-agents) — pipeline stage definitions and Claude Code skills for Medikode's coding, audit, ERA, RAF, and validation agents

## License

ISC © Medikode.ai