Epic Healthcare MCP Server

A production-level Model Context Protocol (MCP) server for Epic Healthcare Systems, designed to securely integrate with Epic's FHIR R4 API and provide AI assistants with access to patient healthcare data.

🏥 Features

• FHIR R4 Compliance: Full integration with Epic's FHIR R4 API
• OAuth 2.0 Authentication: Secure authentication using Epic's OAuth 2.0 with JWT client assertions
• MCP Protocol Support: Standard Model Context Protocol implementation for AI assistant integration
• Production Ready: Comprehensive logging, error handling, and rate limiting
• HIPAA Considerations: Designed with healthcare data security and privacy in mind
• Scalable Architecture: Hybrid Node.js/TypeScript implementation

Available MCP Resources

• Patient Demographics: Access to patient basic information and identifiers
• Clinical Observations: Vital signs, lab results, and clinical measurements
• Medications: Current and historical medication lists
• Allergies: Patient allergy and intolerance information
• Encounters: Healthcare visits and encounter data
• FHIR Metadata: Server capabilities and resource definitions

Available MCP Tools

• search_patients: Search for patients using various criteria
• get_patient_summary: Comprehensive patient data aggregation
• get_vital_signs: Recent vital signs and observations
• search_observations: Query specific clinical observations

Available MCP Prompts

• patient_summary: Generate clinical summary reports
• clinical_assessment: Create clinical assessments from patient data

🚀 Quick Start

Prerequisites

• Node.js 18+
• Epic Healthcare System access
• Epic App registration with FHIR API access
• Valid JWT private key for Epic authentication

Installation

1. Clone and install dependencies:

# Install MCP Server dependencies
cd mcp-server
npm install

# Install MCP Client dependencies (for testing)
cd ../mcp-client
npm install

2. Configure environment variables:

# Copy and configure environment file
cp .env.example .env

Required environment variables:

# Epic FHIR Configuration
EPIC_CLIENT_ID=your-epic-client-id
EPIC_CLIENT_SECRET=your-epic-client-secret
EPIC_FHIR_BASE_URL=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4

# JWT Authentication
JWT_PRIVATE_KEY=your-jwt-private-key
JWT_KEY_ID=your-jwt-key-id

# Server Configuration
MCP_SERVER_PORT=3000
NODE_ENV=production
LOG_LEVEL=info

3. Build and run the server:

cd mcp-server
npm run build
npm start

Testing with MCP Client

Run the included test client to verify functionality:

cd mcp-client
npm run build
npm start

📖 Usage

Integrating with AI Assistants

The Epic Healthcare MCP Server can be integrated with AI assistants that support the Model Context Protocol:

1. Configure the AI assistant to connect to the MCP server
2. Use MCP resources to access patient data contextually
3. Execute MCP tools for specific healthcare queries
4. Leverage MCP prompts for clinical summaries and assessments

Example MCP Tool Usage

{
  "name": "search_patients",
  "arguments": {
    "name": "John Doe",
    "birthdate": "1990-01-01",
    "count": 10
  }
}

{
  "name": "get_patient_summary",
  "arguments": {
    "patientId": "patient-12345"
  }
}

🔧 Configuration

Epic FHIR Setup

1. Register your application with Epic's developer program

2. Configure FHIR scopes for required resource access:

   • system/Patient.read
   • system/Observation.read
   • system/Encounter.read
   • system/Medication.read
   • system/AllergyIntolerance.read

3. Generate JWT key pair for client authentication

4. Configure redirect URLs and authentication endpoints

Security Configuration

• Rate Limiting: Configurable request limits to prevent API abuse
• JWT Authentication: Secure client assertion-based authentication
• HTTPS Only: All API communications use encrypted connections
• Audit Logging: Comprehensive logging for security monitoring

🏗️ Architecture

Epic Healthcare MCP Server
├── mcp-server/              # Main MCP server implementation
│   ├── src/
│   │   ├── auth/            # Epic OAuth 2.0 authentication
│   │   ├── clients/         # Epic FHIR API client
│   │   ├── config/          # Environment and configuration
│   │   ├── mcp/             # MCP protocol implementation
│   │   └── utils/           # Logging and utilities
│   └── dist/                # Built JavaScript files
├── mcp-client/              # Test client for development
└── logs/                    # Application logs

Key Components

• EpicOAuthClient: Handles Epic's OAuth 2.0 JWT authentication
• EpicFHIRClient: Axios-based client for FHIR API interactions
• EpicMCPServer: Core MCP protocol server implementation
• Environment Configuration: Zod-based configuration validation
• Winston Logging: Structured logging for production monitoring

🧪 Development

Running in Development Mode

cd mcp-server
npm run dev

Building the Project

npm run build

Type Checking

npm run type-check

Linting

npm run lint

📋 FHIR Resource Support

Resource Type	Read	Search	Supported Operations
Patient	✅	✅	Demographics, identifiers
Observation	✅	✅	Vital signs, lab results
Encounter	✅	✅	Visits, appointments
MedicationRequest	✅	✅	Prescriptions, medications
AllergyIntolerance	✅	✅	Allergies, intolerances
Condition	✅	✅	Diagnoses, problems
Procedure	✅	✅	Medical procedures

🔒 Security & Compliance

HIPAA Considerations

• Data Minimization: Only request necessary patient data
• Audit Trails: Comprehensive logging of all data access
• Encryption: All data transmission uses TLS encryption
• Access Controls: OAuth 2.0 scoped access to Epic resources

Best Practices

• Store JWT private keys securely
• Rotate authentication tokens regularly
• Monitor API usage and access patterns
• Implement proper error handling to prevent data leakage
• Regular security audits and penetration testing

📚 API Documentation

Epic FHIR API Documentation

• Epic on FHIR
• Epic Developer Portal
• FHIR R4 Specification

MCP Protocol Documentation

• Model Context Protocol Specification
• MCP SDK Documentation

🐛 Troubleshooting

Common Issues

Authentication Failures

• Verify Epic client ID and private key configuration
• Check JWT key ID matches Epic app registration
• Ensure proper OAuth scopes are configured

FHIR API Errors

• Verify Epic FHIR base URL is correct
• Check patient ID format and existence
• Review Epic API rate limits and quotas

MCP Connection Issues

• Verify MCP client configuration
• Check server logs for connection errors
• Ensure proper transport configuration

Logging

Logs are written to:

• logs/combined.log - All application logs
• logs/error.log - Error-level logs only
• Console output in development mode

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with proper tests
4. Submit a pull request

📞 Support

For Epic-specific issues:

• Epic UserWeb Support
• Epic Developer Community

For MCP protocol issues:

• MCP GitHub Repository
• MCP Community Forums