# Healthcare Model Context Protocol (MCP) Demo

A lightweight healthcare demo application showcasing the latest **stateless Model Context Protocol (MCP)** standard using **FastMCP**, **Pydantic AI**, and **Google Gemini**.

This repository demonstrates how to build a secure, server-side MCP infrastructure that exposes clinical read endpoints, state mutation tools, and workflow prompts, then orchestrates them via an AI Host layer.

---

## Key Concepts & Architecture

1. **MCP Resources (Read Operations)**: Exposes passive context via custom URIs (e.g., `healthcare://patients/{patient_id}/record`). Used by the AI model to fetch factual data without side effects.
2. **MCP Tools (Write/Mutation Operations)**: Exposes executable actions (e.g., `update_patient_status`). Converts Python type hints and docstrings into JSON Schemas for AI function calling.
3. **MCP Prompts (Workflow Templates)**: Centralizes clinical prompt logic on the server (e.g., `generate_discharge_summary_prompt`), providing standardized instructions across all client environments.
4. **Transports (HTTP/SSE)**: Runs as a stateless remote server over Server-Sent Events (SSE) on HTTP port `8000`.
5. **Authentication**: Uses Bearer Token authorization to secure remote SSE server connections.
6. **AI Host Integration**: Uses `pydantic-ai` and `google-gla:gemini-2.5-flash` to automatically inspect tools, make clinical decisions, and execute mutations via natural language queries.

---

## Project Structure

```text
healthcare-mcp-demo/
├── server.py               # FastMCP Server (Resources, Tools, Prompts, SSE transport)
├── client.py               # Deterministic host test script (Direct MCP protocol verification)
├── pydantic_llm_client.py  # AI Host script (Pydantic AI + Gemini + MCPToolset + Auth)
├── pyproject.toml          # Project dependencies managed by uv
├── uv.lock                 # Lockfile for precise dependency resolution
└── README.md               # Documentation


----

Prerequisites
Python: 3.10 or higher

Package Manager: uv installed on your system

API Key: Google Gemini API key (GEMINI_API_KEY)

Installation & Setup
Clone or navigate to the repository:

PowerShell
cd healthcare-mcp-demo
Install Dependencies:
uv will automatically set up the virtual environment and install all necessary packages:

PowerShell
uv sync
Configure Environment Variables:
Set your Gemini API key in your terminal session:

PowerShell
# Windows PowerShell
$env:GEMINI_API_KEY="your-actual-gemini-api-key"

# Linux / macOS
export GEMINI_API_KEY="your-actual-gemini-api-key"
Running the Application
Running the demo requires two terminal windows:

Step 1: Start the Remote MCP Server (Terminal 1)
Run the server script using uv:

PowerShell
uv run .\server.py
The server will start listening on http://0.0.0.0:8000/sse.

Step 2: Run the AI Host Client (Terminal 2)
In a second terminal, execute the Pydantic AI client script:

PowerShell
uv run .\pydantic_llm_client.py
Expected Output Workflow
The client establishes an authenticated SSE connection using a Bearer Token (secure-healthcare-secret-token-123).

Pydantic AI sends the user query alongside the discovered MCP tools to Gemini.

Gemini determines that update_patient_status needs to be called.

The MCP Tool executes on server.py, updating the record for patient P-101.

Gemini synthesizes the execution feedback and returns a natural language response:

Plaintext
User Request: 'Please update patient P-101's status to 'Discharged' and set condition to 'Acute Bronchitis - Fully Recovered'.'

Executing request via Gemini + FastMCP...

=== GEMINI RESPONSE ===
The patient record for P-101 has been successfully updated.

* Status: Discharged
* Condition: Acute Bronchitis - Fully Recovered