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:

# Install MCP Server dependencies
cd mcp-server
npm install

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

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

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:

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

{
  "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

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

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

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 logs
logs/error.log - Error-level logs only
Console 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 UserWeb Support
Epic Developer Community

For MCP protocol issues:

MCP GitHub Repository
MCP Community Forums

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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

AgentCare
Kartha-AI
-
security
A
license
-
quality
An MCP server that provides healthcare tools for interacting with FHIR data and medical resources on EMRs like Cerner and Epic
Last updated -
80
MIT License
Smart EHR MCP Server
jmandel
-
security
A
license
-
quality
A 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 -
62
MIT License
NDHM HIU MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
This 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 -
HAPI-MCP
ericmc21
-
security
F
license
-
quality
A Model Context Protocol server that enables querying FHIR healthcare data using natural language, allowing doctors to retrieve patient information, medications, observations, and other healthcare records.
Last updated -
1

View all related MCP servers