vClinic MCP Server

A Model Context Protocol (MCP) server that exposes a virtual clinic's clinical data and knowledge base as tools for AI agents. Agents can manage patients, visits, diagnoses, treatments, lab orders, radiology orders, and search both external medical literature and an internal RAG knowledge base.

Features

All tool calls are audit-logged to data/audit.log (HIPAA § 164.312(b)).

Related MCP server: CharmHealth MCP Server

Project Structure

vClinic-mcp-server/
├── server.py               # MCP server entry point
├── audit_logger.py         # HIPAA audit log decorator
├── sample_client.py        # Test client using langchain-mcp-adapters
├── requirements.txt
├── backend/
│   ├── db.py               # SQLite connection & init
│   └── schema.sql          # Synthea-aligned schema + operational tables
├── tools/
│   ├── patient_tools.py
│   ├── visit_tools.py
│   ├── diagnosis_tools.py
│   ├── treatment_tools.py
│   ├── lab_tools.py
│   ├── radiology_tools.py
│   ├── medical_search_tools.py
│   └── ...
├── rag_tools/
│   └── rag_tools.py        # Pinecone RAG — indexes knowledge_base/
├── knowledge_base/
│   ├── drug_formulary.md
│   ├── clinical_protocols.md
│   └── clinic_sops.md
└── data/
    ├── vclinic.db          # SQLite database (created on first run)
    └── audit.log           # Append-only CSV audit trail

Requirements

• Python 3.11+

• Pinecone local dev server running on http://localhost:5080

• OpenAI API key (for text-embedding-3-small embeddings and agent LLM calls)

Setup

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Set your OpenAI API key
export OPENAI_API_KEY=sk-...

Running the Server

# Normal start — creates the DB on first run, loads the Pinecone index
python -m server

# Wipe and recreate the database (drops all patient data)
python -m server --reinit

On startup the server will:

1. Create data/vclinic.db and seed default staff (first run only, or with --reinit).

2. Build or load the Pinecone knowledge-base index (vclinic-knowledge).

Running the Sample Client

The sample client connects to the server over stdio and lists all registered tools:

python sample_client.py

# Start the server with a fresh database
VCLINIC_REINIT=1 python sample_client.py

Knowledge Base (RAG)

Internal clinic documents in knowledge_base/ are indexed into Pinecone at server startup:

The search_clinic_knowledge tool performs semantic search over these documents. If the Pinecone index already exists and contains vectors it is reused; otherwise it is built from scratch (requires an active OpenAI API key).

To force a re-index, delete the Pinecone index and restart the server.

Audit Logging

Every tool call is appended to data/audit.log as a CSV row containing:

VS Code / Claude Desktop Configuration

{
  "mcpServers": {
    "vclinic": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/vClinic-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

⚠️ License & Disclaimer

This project is a Proof of Concept (POC) and is intended solely for demonstration and educational purposes.

• No Liability: The code owner accepts no responsibility for any damages, data loss, or issues caused by running this software.

• As-Is: This software is provided as-is, without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement.

• Not for Clinical Use: This system must not be used to inform, support, or replace real clinical decisions, diagnoses, or patient care of any kind. All data used is fully synthetic and has no connection to real patients or medical records.

• License: Distributed under the MIT License.