# Healthcare Clinic MCP Server

An MCP (Model Context Protocol) server that exposes appointment scheduling
and insurance claims data as standardized tools -- so any MCP-compatible
AI client (Claude Desktop, Claude Code, or a custom agent) can query and
update clinic data without a one-off, hand-rolled integration.

## Why this project

Most AI-agent portfolios show agents that *talk*. Very few show the
infrastructure layer that lets agents *act* on real systems in a
standardized way. MCP is the emerging protocol for exactly that --
this project demonstrates building the server side of it, which is a
comparatively rare skill in most AI engineering portfolios right now.

This server exposes the same kind of data an insurance-claims agent (see
the separate insurance-claims-multi-agent project in this portfolio) would
need to call in a real deployment -- scheduling and claims records --
through a protocol any agent can plug into, instead of custom code per
integration.

## What it exposes

**Appointment tools**
- `get_appointment(appointment_id)` -- look up one appointment
- `list_appointments_for_patient(patient_name)` -- all appointments for a patient
- `create_appointment(...)` -- book a new appointment

**Claims tools**
- `check_claim_status(claim_id)` -- look up one claim's status
- `list_claims_for_patient(patient_name)` -- all claims for a patient
- `create_claim(...)` -- submit a new claim record

All data lives in a local SQLite database (`clinic.db`), which stands in
for a real practice-management/EHR system. In a production deployment,
these same tool functions would call a real database or API instead.

## Tech stack

| Component | Tool | Why |
|---|---|---|
| Protocol | MCP Python SDK (stable v1.x) | Official SDK; v2 is a breaking-change beta as of writing -- see note below |
| Data | SQLite | Simple, no setup, good stand-in for a real EHR/PM system |

**Version note:** The MCP Python SDK is mid-migration to a v2 with
breaking protocol changes (targeted stable release 2026-07-28). This
project pins `mcp<2` deliberately so it keeps working. Check
[the SDK's release notes](https://github.com/modelcontextprotocol/python-sdk/releases)
before upgrading.

## Setup

### 1. Install dependencies

```bash
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Create the demo database

```bash
python database.py
```

This creates `clinic.db` with a few synthetic appointments and claims
(no real patient data).

### 3. Test it with the MCP Inspector (visual, no client needed)

```bash
mcp dev server.py
```

This opens a browser-based inspector where you can call each tool
directly and see the request/response -- the fastest way to demo this
project without needing Claude Desktop installed.

### 4. Install it into Claude Desktop (optional)

```bash
mcp install server.py --name "Healthcare Clinic Tools"
```

Restart Claude Desktop, and you'll be able to ask Claude things like
*"What's the status of claim CLM-2002?"* and it will call the tool
directly.

## Example tool calls

```python
check_claim_status("CLM-2002")
# -> {"claim_id": "CLM-2002", "patient_name": "Jordan Reyes",
#     "cpt_code": "73721", "icd10_code": "M25.561",
#     "status": "under_review", "submitted_date": "2026-07-10"}

list_appointments_for_patient("Jordan")
# -> [{"appointment_id": "APT-001", "patient_name": "Jordan Reyes", ...}]
```

## What I'd improve next

- Add write-conflict handling for concurrent appointment bookings
- Add MCP Resources (not just Tools) to expose read-only clinic policy
  documents alongside the live data
- Swap SQLite for a real practice-management system's API in a
  production deployment

## Disclaimer

All data in `database.py` is synthetic and created for demonstration
purposes only. No real patient data is used or stored anywhere in this
project.