clinic-mcp-server

MCP Server: Company Data as Claude Tools.

Expose a clinic's knowledge base and structured records to Claude Desktop (or any MCP client) as callable tools — with the same grounding discipline as docs-rag-chatbot: read tools grounded with citations; write tools gated behind approval.

That contrast is the pitch. Anyone can wrap a search endpoint. Showing you thought about what happens when an agent can change something is what senior looks like.

Architecture

Claude Desktop (stdio MCP)
        │
        ▼
 clinic-mcp-server
   ├─ search_clinic_docs  → hybrid RRF over shared `chunks` (pgvector + tsvector)
   │                         + SIMILARITY_FLOOR gate → citations or "no relevant sources"
   ├─ get_patient_record  → Postgres `patients` (+ next confirmed appointment)
   ├─ list_appointments   → parameterized date-range query on `appointments`
   └─ create_appointment  → INSERT into `appointment_requests` (pending only)
                             NEVER writes confirmed `appointments`

Shares DATABASE_URL with docs-rag-chatbot (same Postgres). Retrieval code is local; the RAG chunks table is reused as-is. Clinic tables (patients, appointments, appointment_requests) are additive.

Related MCP server: vClinic MCP Server

Prerequisites

1. Postgres/pgvector running for docs-rag-chatbot with docs ingested (make up && make ingest there).

2. Python 3.12 + uv.

Quick start (two minutes)

cd clinic-mcp-server
uv sync
cp .env.example .env   # DATABASE_URL should match docs-rag-chatbot

# Create clinic tables + seed Jordan Lee et al. (does not touch chunks)
make setup

# Smoke-test over stdio (or point Claude Desktop at it — see below)
make serve

Claude Desktop config

Add this to your Claude Desktop claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Use absolute paths:

{
  "mcpServers": {
    "clinic": {
      "command": "/Users/leovet/.cargo/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/leovet/freelance/clinic-mcp-server",
        "python",
        "-m",
        "clinic_mcp"
      ]
    }
  }
}

Restart Claude Desktop. You should see four tools under the clinic server.

A ready-to-merge example lives at claude_desktop_config.example.json.

Tip: find uv with which uv if your install path differs.

Demo (~60s)

1. Open Claude Desktop with the MCP server connected — show the four tools.

2. Ask: "Do you accept Delta Dental PPO?"
   → Claude calls search_clinic_docs, answers with a source citation (e.g. 06_insurance_faq.md).

3. Ask: "when is Jordan Lee's next appointment?"
   → Claude calls get_patient_record with jordan-lee, returns structured data (insurance, upcoming crown consult).

4. Ask: "book Jordan a crown consult next Tuesday"
   → Claude calls create_appointment; response is pending_approval — nothing committed to the confirmed calendar.

5. Close: "Read tools answer. The write tool proposes and waits for a human."

Tools

Demo patient id: jordan-lee.

Config (.env)

Makefile

make sync     # uv sync --extra dev
make setup    # schema + seed
make schema   # clinic tables only
make seed     # demo patients / appointments
make serve    # stdio MCP server
make test     # pytest

Safety contract

• Grounded reads: search_clinic_docs refuses weak matches instead of returning noise Claude could cite.

• Loud failures: DB outages raise [db_unavailable] … tool errors. Empty appointment lists are only returned when the query succeeded.

• Guarded writes: create_appointment never inserts into appointments. A human must approve the pending request before anything is confirmed.

• Out of scope (intentionally): auth, multi-tenancy, OAuth, remote hosting, MCP resources/prompts. Four tools done well beats twelve half-wired.

Tests

make test

Covers tool discovery/schemas, Pydantic validation, retrieval gate + citations, structured errors, patient/appointment lookups, and the invariant that write calls create pending requests only.