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

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