clinic-mcp

A reference Model Context Protocol server for clinic scheduling and intake. Built in TypeScript with strict typing, structured errors, and tenant isolation enforced at the data layer. The data is synthetic. This is not clinical software.

The goal is to show what a production-shaped MCP server looks like for a vertical that demands data isolation and grounded outputs: the same shape of code I write at Rentive, with mock data and a different domain so the patterns are reviewable without leaking anything proprietary.

Why MCP

LLM applications keep reinventing the same wiring: ad-hoc function definitions per provider, bespoke argument parsing, no shared transport, no consistent error model. MCP is a small open protocol that fixes the wiring layer. A server exposes a list of typed tools over stdio (or HTTP), and any MCP-aware client (Claude Desktop, IDE integrations, custom agents) can discover and call them with the same machinery.

For domain backends, that means you write tools once and they work everywhere. For agent builders, it means you stop hand-rolling tool schemas and start composing servers.

Architecture

flowchart LR
    Client["MCP client<br/>(Claude Desktop, custom agent)"]
    Server["clinic-mcp server"]
    Tools["Tools<br/>find_available_slot<br/>book_appointment<br/>record_intake<br/>search_protocols<br/>escalate_to_oncall"]
    Store["ClinicStore<br/>tenant-scoped accessors"]
    Seed[("seed.json<br/>synthetic clinics, providers,<br/>patients, protocols")]

    Client -->|stdio JSON-RPC| Server
    Server --> Tools
    Tools --> Store
    Store --> Seed

Every tool takes a clinic_id and the store enforces that all reads and writes are scoped to that clinic. Cross-tenant access throws TenantMismatchError rather than silently returning the wrong row. This mirrors the row-level-security pattern a production deployment would enforce in Postgres, surfaced here in application code so the guarantee is reviewable in one file (src/store/index.ts).

Run it locally

Requires Node 20+ and pnpm.

git clone https://github.com/dominikstefanski/clinic-mcp.git
cd clinic-mcp
pnpm install
pnpm test          # 29 tests
pnpm typecheck
pnpm dev           # boots the server on stdio

The server reads src/store/seed.json at startup and serves two synthetic clinics: clinic_north (general practice, cardiology, dermatology) and clinic_west (pediatrics, general practice).

Wire into Claude Desktop

Add this to your Claude Desktop config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Replace the path with your local clone.

{
  "mcpServers": {
    "clinic-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/clinic-mcp/src/server.ts"]
    }
  }
}

Restart Claude Desktop. The five tools will appear under the connections menu. Try a prompt like "Find a general practice opening at clinic_north next Monday morning."

Tool reference

All tools return { ok: true, ...result } on success or { ok: false, error: { code, message } } on failure. Inputs are validated with zod; MCP-level argument errors are returned as validation errors with field details.

find_available_slot

Find open appointment slots for a specialty in a date range, skipping conflicts.

Field	Type	Notes
clinic_id	string	Required
specialty	enum	general_practice | pediatrics | cardiology | dermatology
from_iso	string	Inclusive ISO 8601 start
to_iso	string	Exclusive ISO 8601 end
duration_minutes	int	15 to 120, default 30
limit	int	1 to 50, default 10

book_appointment

Create an appointment. Requires a caller-supplied idempotency_key; replays return the original appointment instead of double-booking. Voice agents will retry, so this is non-optional.

Field	Type	Notes
clinic_id	string	Required
provider_id	string	Must belong to clinic_id
patient_id	string	Must belong to clinic_id
start_iso	string	ISO 8601
duration_minutes	int	15 to 120, default 30
reason	string	1 to 500 chars
idempotency_key	string	8 to 128 chars, caller-supplied

Returns { appointment, idempotent_replay }.

record_intake

Persist a structured intake note and assign a triage level.

Field	Type	Notes
clinic_id	string	Required
patient_id	string	Must belong to clinic_id
symptoms	string[]	1 to 20 entries
severity	int	1 to 10, patient-reported
onset_iso	string	ISO 8601
notes	string	Optional, max 2000 chars

Triage rule: severity >= 8 is urgent, >= 5 is elevated, otherwise routine.

search_protocols

Keyword search over the clinic's protocol library. Returns ranked snippets the model can cite when answering.

Field	Type	Notes
clinic_id	string	Required
query	string	1 to 500 chars
limit	int	1 to 20, default 5

The current implementation is a naive TF score with title weighting (3x). It exists to demonstrate the interface of a retrieval tool; production deployments would swap the backend for vector search (see Design notes).

escalate_to_oncall

Mark an existing appointment as urgent and reassign it to the clinic's on-call provider.

Field	Type	Notes
clinic_id	string	Required
appointment_id	string	Must belong to clinic_id
reason	string	1 to 500 chars, appended to the appointment's reason

Returns { appointment, on_call_provider, reassigned }.

Design notes

Tenant isolation is enforced at the store, not the tool. Tools accept a clinic_id and pass it down. The store validates ownership on every accessor and throws TenantMismatchError on mismatch. If you add a new tool tomorrow, you cannot accidentally leak across clinics; the store will not let you.

Idempotency on writes. book_appointment requires an idempotency_key. Real callers (voice agents, retry loops, network blips) will repeat requests, and a healthcare system that responds to retries by creating duplicate appointments is a healthcare system that loses trust on day one.

Structured errors over thrown strings. Every domain failure is a typed DomainError subclass with a stable code. The MCP wrapper turns them into { ok: false, error: { code, message } }. Clients can branch on code instead of regexing message.

The retrieval tool is a stand-in. search_protocols uses an in-memory TF score so the repo runs without external services. In production this is the seam where you wire in Pinecone, pgvector, or your retrieval backend of choice. The tool's input/output contract stays the same.

Time handling is simplified. Provider working hours are interpreted in UTC for clarity. A real deployment would respect each clinic's timezone (already in the schema). Calling this out explicitly so reviewers know it's intentional, not an oversight.

What this isn't

• Not clinical software. The triage rule is a toy and the protocol corpus is hand-written prose. Do not use it for anything that touches real patients.
• Not HIPAA-compliant. The data is fake, the storage is in-memory, there is no audit log. Production would need all of that and then some.
• Not a complete EMR or scheduling backend. The point is to show the MCP-server shape, not to ship a clinic system.

License

MIT. See LICENSE.