This MCP server provides an AI agent (like Claude Desktop) with tools to interact with a clinic's knowledge base and appointment system, with safety guards:
search_clinic_docs(query, top_k=5): Hybrid search (pgvector dense similarity + full-text, fused via Reciprocal Rank Fusion) over clinic documents. Returns cited chunks only if above a similarity threshold; otherwise reports no_relevant_sources to prevent fabrication.
get_patient_record(patient_id): Retrieves patient details (name, contact, insurance, last visit) and the next confirmed appointment. Errors if patient missing or DB down.
list_appointments(date_from, date_to): Lists confirmed appointments in the inclusive date range. Empty list means none found; DB failures raise errors.
create_appointment(patient_id, datetime, service): Creates a pending appointment request (status='pending') requiring human approval before being confirmed. Never directly modifies the confirmed calendar.
Safety contract: Read tools are grounded with citations or explicit "no relevant sources"; database errors result in tool errors; the write tool only creates pending requests gated by human approval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clinic-mcp-server Do you accept Delta Dental PPO?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: Patient Data MCP Server
Postgres/pgvector running for docs-rag-chatbot with docs ingested (make up && make ingest there).
Python 3.12 + uv.
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 serveAdd 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
uvwithwhich uvif your install path differs.
Open Claude Desktop with the MCP server connected — show the four tools.
Ask: "Do you accept Delta Dental PPO?"
→ Claude calls search_clinic_docs, answers with a source citation (e.g. 06_insurance_faq.md).
Ask: "when is Jordan Lee's next appointment?"
→ Claude calls get_patient_record with jordan-lee, returns structured data (insurance, upcoming crown consult).
Ask: "book Jordan a crown consult next Tuesday"
→ Claude calls create_appointment; response is pending_approval — nothing committed to the confirmed calendar.
Close: "Read tools answer. The write tool proposes and waits for a human."
Tool | Mode | Behavior |
| read | Hybrid retrieval; below |
| read | Patient row + next confirmed appointment. Missing patient / DB down → tool error (not empty success). |
| read | Confirmed appointments in an inclusive date window (clinic TZ). Empty list is valid; DB failure is an error. |
| write (gated) | Inserts |
Demo patient id: jordan-lee.
.env)Variable | Purpose | Default |
| Shared Postgres (same as RAG app) |
|
| Dense cosine gate for doc search |
|
| Timezone for date windows / naive datetimes |
|
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 # pytestGrounded 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.
make testCovers tool discovery/schemas, Pydantic validation, retrieval gate + citations, structured errors, patient/appointment lookups, and the invariant that write calls create pending requests only.
Propose a new appointment — does NOT confirm it.
Inserts a row into appointment_requests with status=pending and returns
pending_approval. A human must approve before anything lands on the
confirmed appointments calendar. Calling this twice creates two pending
requests; it never silently books.
Inputs: service (required), datetime (required), patient_id (required). Returns: Write tool always returns a *pending* request — never a confirmed booking.
Look up a patient by id: name, insurance, last visit, and next confirmed appointment.
Raises a tool error if the patient does not exist or the database is down —
never returns an empty success that could be mistaken for 'no appointments'.
Inputs: patient_id (required). Returns: status, patient
List confirmed appointments between date_from and date_to (inclusive).
date_to must be on or after date_from. Empty list with status=ok means no
confirmed appointments in that window — distinct from a database failure,
which raises a tool error.
Inputs: date_to (required), date_from (required). Returns: count, status, date_to, date_from, +1 more
Hybrid-search the clinic knowledge base (pgvector + full-text, RRF-fused).
Returns cited chunks with source filename and scores when the best dense
similarity clears the SIMILARITY_FLOOR gate. Below that floor, returns
status=no_relevant_sources with an empty chunk list — do not fabricate
an answer from weak matches.
Inputs: query (required), top_k. Returns: query, chunks, status, message, +2 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool addresses a distinct task: searching knowledge base, retrieving patient record, listing appointments, and creating appointment requests. No functional overlap exists.
All tools follow a consistent verb_noun snake_case pattern (search_clinic_docs, get_patient_record, list_appointments, create_appointment).
4 tools are well-scoped for a clinic management server, covering search, patient lookup, appointment listing, and appointment creation. Neither too few nor too many.
The set covers basic read and create operations, but lacks tools for updating patient records, confirming/cancelling appointments, or deleting requests, which are notable gaps for a full appointment management workflow.
Telehealth support for Claude, Codex and Cursor: investigate cases and connect your tools.
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Your SMB workspace in Claude or ChatGPT: tasks, notes, sales and Michèle's memory, via OAuth.
Connect Claude to Fathom meeting recordings, transcripts, and summaries
