HIPAA-Compliant MCP Security Proxy for Healthcare AI Agents

Overview

A minimal transparent proxy that forwards HTTP requests/responses between locally implemented Claude Code and healthcare API endpoints. The proxy does not process or store protected health information (PHI); HIPAA compliance responsibilities are delegated to the downstream healthcare APIs. It is intended for developers building AI-driven healthcare applications who need a simple, dependency-free forwarding layer during local development or testing.

Problem Statement

Healthcare AI agents often need to interact with external APIs that handle PHI. Directly exposing these APIs to local development tools can create security gaps and complicate HIPAA compliance efforts. Existing solutions introduce heavyweight middleware or external dependencies, increasing attack surface and maintenance overhead. A lightweight, transparent proxy that simply forwards traffic lets developers keep compliance handling in the healthcare APIs while maintaining a clean local development workflow.

Features

• Transparent HTTP forwarding -- passes requests and responses unchanged between Claude Code and healthcare endpoints.
• Basic error handling -- returns appropriate status codes (e.g., 500) when the target API is unreachable.
• Zero external dependencies -- runs solely with Node.js core modules; no npm packages required.
• Self-contained -- all logic resides in src/proxy.js and src/server.js.
• Minimal configuration -- configurable via environment variables or command-line arguments (see Usage).

Tech Stack

• Language: JavaScript (Node.js)
• Runtime: Node.js >= 16 (uses only built-in http, https, url, stream modules)
• Package Manager: npm (for lockfiles only; no runtime dependencies)
• Operating System: Cross-platform (Linux, macOS, Windows)

Quick Start / Installation

1. Clone the repository

   git clone https://github.com/m2ai-portfolio/hipaa-compliant-mcp-security-proxy-for-healthcare-ai-agents.git
   cd hipaa-compliant-mcp-security-proxy-for-healthcare-ai-agents

2. Install (optional) -- the project has no runtime dependencies, but you can run npm install to lock the environment.

   npm install

3. Make the init script executable (if you prefer the provided helper).

   chmod +x init.sh

4. Start the proxy (see Usage for configuration options).

Usage

Run the proxy directly with Node:

node src/server.js

By default the server listens on port 3000 and forwards to a target healthcare API defined by the TARGET_API environment variable.

Environment variables

Variable	Description	Default
TARGET_API	Base URL of the healthcare API (e.g., https://api.example.com/v1)	required
PORT	Port on which the proxy listens	3000
LOG_LEVEL	Verbosity of console output (info, warn, error)	info

Example

TARGET_API=https://fhir.server.com PORT=4000 LOG_LEVEL=warn node src/server.js

The proxy will now accept requests at http://your-server:4000/<path> and forward them to https://fhir.server.com/<path>, returning the upstream response unchanged.

Architecture

• src/server.js -- creates an HTTP(S) server using Node's core http module. It parses incoming requests, builds a proxied request to the target API, pipes the response back to the client, and handles basic error cases (connection failures, timeouts).
• src/proxy.js (optional helper) -- encapsulates the forwarding logic; currently used by server.js for readability but could be reused elsewhere.
• No database, no external services, no build step. All state is held in memory for the lifetime of the process.

License

MIT

---

Feel free to open issues or submit pull requests to improve the proxy or add healthcare-specific utilities.