Uses Axios as the HTTP client for making requests to Epic's FHIR R4 API endpoints
Uses environment variables for configuration management of Epic authentication credentials and server settings
Built using JavaScript/Node.js runtime for the MCP server implementation
Runs on Node.js 18+ runtime environment for the MCP server implementation
Uses npm package manager for dependency management and project scripts
Implements hybrid Node.js/TypeScript architecture for type-safe development
Uses Zod for environment configuration validation and type checking
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
Clone and install dependencies:
Configure environment variables:
Required environment variables:
Build and run the server:
Testing with MCP Client
Run the included test client to verify functionality:
๐ Usage
Integrating with AI Assistants
The Epic Healthcare MCP Server can be integrated with AI assistants that support the Model Context Protocol:
Configure the AI assistant to connect to the MCP server
Use MCP resources to access patient data contextually
Execute MCP tools for specific healthcare queries
Leverage MCP prompts for clinical summaries and assessments
Example MCP Tool Usage
๐ง Configuration
Epic FHIR Setup
Register your application with Epic's developer program
Configure FHIR scopes for required resource access:
system/Patient.read
system/Observation.read
system/Encounter.read
system/Medication.read
system/AllergyIntolerance.read
Generate JWT key pair for client authentication
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
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
Building the Project
Type Checking
Linting
๐ 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
MCP Protocol 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 logslogs/error.log
- Error-level logs onlyConsole output in development mode
๐ License
MIT License - see LICENSE file for details.
๐ค Contributing
Fork the repository
Create a feature branch
Make changes with proper tests
Submit a pull request
๐ Support
For Epic-specific issues:
Epic Developer Community
For MCP protocol issues:
MCP Community Forums
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI assistants to securely access Epic Healthcare Systems patient data through FHIR R4 API integration. Provides tools for searching patients, retrieving clinical summaries, vital signs, medications, and generating healthcare reports with HIPAA-compliant OAuth 2.0 authentication.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that provides healthcare tools for interacting with FHIR data and medical resources on EMRs like Cerner and EpicLast updated -82MIT License
- -securityAlicense-qualityA Model Context Protocol server that connects AI tools to Electronic Health Records using SMART on FHIR, allowing secure searching, querying, and analysis of patient data from compatible EHRs.Last updated -63MIT License
- -securityFlicense-qualityThis server enables interacting with the National Digital Health Mission's Health Information User (HIU) API, allowing agents to access and manage health information through the Multi-Agent Conversation Protocol.Last updated -