Documentation

Overview

SecureHospital AI is an enterprise-grade healthcare AI demonstration platform that showcases how to safely integrate Large Language Models (LLMs) with sensitive healthcare data. It implements a three-layer security architecture using Django, FastAPI, and the Model Context Protocol (MCP).

Architecture

The system uses a three-layer security model where each layer provides independent protection:

┌─────────────────────────────────────────────────────────────────┐
│                        USER INTERFACE                            │
│                    (React / HTML Dashboard)                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LAYER 1: DJANGO BACKEND                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Auth &    │  │   Session   │  │    LLM Handler          │  │
│  │    JWT      │  │  Management │  │  (OpenAI Integration)   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LAYER 2: OPENAI GPT-4                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  System Prompt with Security Guidelines + Tool Schemas   │    │
│  │  • Cannot reveal PHI without authorization               │    │
│  │  • Must call MCP tools for data access                   │    │
│  │  • Respects role-based restrictions                      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LAYER 3: MCP SERVER (FastAPI)                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │    RBAC      │  │    Audit     │  │    Data Access       │   │
│  │  Enforcement │  │   Logging    │  │    (PostgreSQL)      │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Component Overview

Features

Security Features

• JWT Authentication - Secure token-based auth with refresh tokens
• Role-Based Access Control - 6 predefined roles with granular permissions
• Audit Logging - Every tool call logged to database
• PHI Redaction - Sensitive data hidden from unauthorized roles
• Session Management - Isolated chat sessions per user

AI Features

• Natural Language Queries - Ask questions in plain English
• Tool Calling - AI decides which MCP tools to invoke
• Streaming Responses - Real-time SSE streaming
• Context Persistence - Remembers patient context across messages
• Auto Chat Titles - Automatic naming based on first message

MCP Tools

Prerequisites

Before running SecureHospital AI locally, ensure you have:

Local Setup

Follow these steps to run SecureHospital AI on your local machine:

BashCopy
git clone https://github.com/yourusername/securehospital-ai.git
cd securehospital-ai

BashCopy
# Create virtual environment
python -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

BashCopy
# Install Django backend dependencies
pip install -r requirements.txt

# Install MCP server dependencies
pip install -r mcp_server/requirements.txt

BashCopy
# Copy example environment file
cp .env.example .env

# Edit with your settings
nano .env

.envCopy
# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/securehospital

# OpenAI
OPENAI_API_KEY=sk-your-openai-api-key

# MCP Server
MCP_SERVER_URL=http://localhost:8001

BashCopy
# Create database
createdb securehospital

# Run migrations
python manage.py migrate

BashCopy
# Terminal 1: Start Django server
python manage.py runserver

# Terminal 2: Start MCP server
cd mcp_server
uvicorn main:app --port 9000 --reload

Visit the demo data import page in your browser:

URLCopy
http://localhost:8000/seed-data/

Click the "Import Demo Data" button and wait for the import to complete. You'll see counts for all created records:

• 6 Demo accounts (Admin, Doctor, Nurse, Billing, Reception, Auditor)
• 50 Patients with PHI records
• 100 Appointments
• 80 Medical records
• Staff shifts and audit logs

Demo Data Import

SecureHospital AI includes a web-based demo data importer that creates sample patients, staff, and medical records with a single click.

Import via Web Interface

The easiest way to populate your database with demo data:

URLCopy
http://localhost:8000/seed-data/

What Gets Created

Demo Account Credentials

All demo accounts use the same password:

Docker Setup

For containerized deployment, use Docker Compose:

BashCopy
# Build and start all services
docker-compose up --build

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Compose Services

Environment Variables

Full list of configurable environment variables:

Database Configuration

SecureHospital AI uses PostgreSQL for storing EHR data, audit logs, and user sessions. The database schema is managed through Django migrations.

Connection Setup

Configure your database connection in the .env file:

.envCopy
# Option 1: Full connection URL (recommended for production)
DATABASE_URL=postgresql://user:password@localhost:5432/securehospital

# Option 2: Individual parameters (for development)
PGHOST=localhost
PGPORT=5432
PGDATABASE=securehospital
PGUSER=your_username
PGPASSWORD=your_password

# MCP Server uses separate connection (can be same DB)
DATABASE_URL_MCP=postgresql://user:password@localhost:5432/securehospital

Database Schema

The application creates several key tables:

Migrations

BashCopy
# Create migrations after model changes
python manage.py makemigrations

# Apply migrations to database
python manage.py migrate

# Load sample data for demo
python manage.py loaddata sample_data.json

OpenAI Setup

SecureHospital AI uses OpenAI's GPT models for natural language processing and function calling to interact with the MCP tools.

API Key Configuration

Obtain an API key from platform.openai.com and add it to your .env file:

.envCopy
# Required: Your OpenAI API key
OPENAI_API_KEY=sk-your-api-key-here

# Optional: Specify model (default: gpt-4o-mini)
OPENAI_MODEL=gpt-4o-mini

Supported Models

Function Calling

The LLM uses OpenAI's function calling feature to invoke MCP tools. Tool definitions are passed in the system prompt:

PythonCopy
MCP_TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_patient_phi",
            "description": "Get Protected Health Information...",
            "parameters": {
                "type": "object",
                "properties": {
                    "patient_id": {"type": "string"}
                },
                "required": ["patient_id"]
            }
        }
    },
    # ... other tools
]

Streaming Responses

The chat interface uses Server-Sent Events (SSE) for real-time streaming:

PythonCopy
# Streaming is handled by StreamingLLMAgent
async for chunk in agent.stream_chat(user_message):
    yield f"data: {json.dumps(chunk)}\n\n"

MCP Server Configuration

The Model Context Protocol (MCP) server is a FastAPI application that provides the security layer between the LLM and your database. It enforces RBAC, performs PHI redaction, and logs all access attempts.

Server Configuration

.envCopy
# MCP Server URL (Django connects here)
MCP_SERVER_URL=http://localhost:9000

# JWT Authentication (must match Django's SECRET_KEY)
SECRET_KEY=your-django-secret-key

# Database connection for MCP server
DATABASE_URL_MCP=postgresql://user:password@localhost:5432/securehospital

# Optional: SSL mode for database
MCP_DB_SSLMODE=require

Starting the MCP Server

BashCopy
# Development mode with auto-reload
cd mcp_server
uvicorn main:app --host 0.0.0.0 --port 9000 --reload

# Production mode
uvicorn main:app --host 0.0.0.0 --port 9000 --workers 4

Available MCP Tools

The MCP server exposes these JSON-RPC tools:

PHI Redaction by Role

The MCP server automatically redacts PHI based on user role:

JSON-RPC Protocol

The MCP server uses JSON-RPC 2.0 for communication:

JSON RequestCopy
{
    "jsonrpc": "2.0",
    "id": "unique-request-id",
    "method": "tools.call",
    "params": {
        "name": "get_patient_phi",
        "arguments": {"patient_id": "FCE57"}
    }
}

JSON Response (Success)Copy
{
    "jsonrpc": "2.0",
    "id": "unique-request-id",
    "result": {
        "data": {
            "patient_id": "FCE57",
            "insurance_provider": "BlueCross",
            "insurance_number": "BC-12345",
            "_access_level": "insurance_only"
        }
    }
}

Health Check

Verify the MCP server is running:

BashCopy
curl http://localhost:9000/health
# Response: {"status": "ok", "service": "mcp-server", "version": "2.0"}

Role-Based Access Control

SecureHospital AI implements healthcare-specific RBAC with 6 predefined roles:

Audit Logging

Every data access is logged to the audit_log table:

SQL SchemaCopy
CREATE TABLE audit_log (
    id UUID PRIMARY KEY,
    timestamp TIMESTAMP NOT NULL,
    user_id UUID REFERENCES users(id),
    staff_id UUID REFERENCES staff(staff_id),
    action VARCHAR(50) NOT NULL,
    table_name VARCHAR(100),
    record_id VARCHAR(100),
    details JSONB,
    ip_address VARCHAR(45),
    user_agent TEXT
);

Logged Actions

• TOOL_CALL - MCP tool invocation
• ACCESS_GRANTED - Successful data access
• ACCESS_DENIED - RBAC rejection
• PHI_ACCESS - Protected data viewed
• LOGIN / LOGOUT - Session events

PHI Protection

Protected Health Information (PHI) includes:

• Social Security Numbers
• Full addresses
• Phone numbers
• Insurance policy numbers
• Medical record numbers
• Detailed diagnosis information

Troubleshooting

Common Issues

MCP Server Connection Failed

Error
ConnectionError: Unable to connect to MCP server

Solution: Ensure the MCP server is running on port 8001. Check MCP_SERVER_URL in your .env file.

OpenAI API Error

Error
openai.AuthenticationError: Invalid API key

Solution: Verify your OPENAI_API_KEY is correct and has sufficient credits.

Database Connection Error

Error
django.db.utils.OperationalError: connection refused

Solution: Ensure PostgreSQL is running and DATABASE_URL is correct.

Async/Sync Django Error

Error
SynchronousOnlyOperation: You cannot call this from an async context

Solution: Wrap Django ORM calls with @sync_to_async decorator in async functions.