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-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

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 before upgrading.

Setup

1. Install dependencies

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

2. Create the demo database

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)

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)

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

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.