athenahealth MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with athenahealth's clinical data and services for AI-powered clinical decision support.

📊 Tool Status Overview

Status	Count	Percentage
✅ Working in Sandbox	5	38%
❌ Not Working (Sandbox Limitations)	8	62%
🧪 Total Tools	13	100%

Features

🏥 Clinical Decision Support

• Patient Data Access: Comprehensive patient information including demographics, medical history, and clinical data
• Prescription Management: Medication history, drug interaction checking, and prescription creation (Production only)
• Provider Management: Healthcare provider directory and practice information
• Clinical Alerts: Real-time clinical decision support alerts and warnings (Production only)
• Lab Results: Access to laboratory results and diagnostic reports (Production only)
• Vital Signs: Patient vital signs history and trending (Production only)

🔒 HIPAA Compliance

• Data Sanitization: Automatic sanitization of sensitive healthcare data in logs
• Audit Logging: Comprehensive audit trails for all data access and modifications
• Access Controls: Role-based access controls and authentication
• Data Encryption: Secure data transmission and storage

🚀 AI-Powered Workflows

• Clinical Assessment: AI-powered clinical assessment prompts
• Medication Review: Automated medication review and optimization (handles sandbox limitations)
• Care Plan Generation: Evidence-based care plan development
• Clinical Summarization: Comprehensive patient clinical summaries

Installation

Prerequisites

• Node.js 18.0.0 or later
• athenahealth Developer Account and API credentials
• TypeScript 5.0.0 or later

Quick Start

Option 1: Use with Claude Desktop (MCP)

1. Clone the repository

   git clone https://github.com/ophydami/athenahealth-mcp-server.git
   cd athenahealth-mcp-server
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp config/environment.example .env
   # Edit .env with your athenahealth API credentials
   

4. Build the project

   npm run build
   

5. Start the MCP server

   npm start
   

6. Configure Claude Desktop

   claude mcp add athenahealth-mcp
   

Option 2: Use with n8n (Webhook Bridge)

If you prefer using n8n for workflow automation instead of Claude Desktop, you can use the webhook bridge:

1. Complete steps 1-4 above

2. Start the webhook bridge server

   npm run webhook-bridge
   

   The server will start on http://localhost:3000 (configurable via WEBHOOK_PORT env variable)

3. Use in n8n workflows

   In your n8n workflow, add an HTTP Request node with:

   • Method: GET or POST (depending on endpoint)
   • URL: http://localhost:3000/[endpoint]
   • Authentication: None (handled by environment variables)
   • Body: JSON (for POST requests)

   Example n8n HTTP Request nodes:

   List Departments:

   Method: GET
   URL: http://localhost:3000/departments
   

   Search Patients:

   Method: POST
   URL: http://localhost:3000/patients/search
   Body: {
     "lastname": "Smith",
     "firstname": "John"
   }
   

   Create Patient:

   Method: POST
   URL: http://localhost:3000/patients
   Body: {
     "firstname": "John",
     "lastname": "Test",
     "dob": "05/20/1985",
     "sex": "M",
     "department_id": "1",
     "email": "john.test@example.com",
     "mobile_phone": "6179876543"
   }
   

   Get Clinical Summary:

   Method: GET
   URL: http://localhost:3000/patients/134/clinical?include_allergies=true&include_prescriptions=true
   

4. View available endpoints

   Navigate to http://localhost:3000/ in your browser to see all available endpoints and their documentation.

Configuration

Environment Variables

Variable	Description	Required	Default
ATHENA_CLIENT_ID	athenahealth API Client ID	Yes	-
ATHENA_CLIENT_SECRET	athenahealth API Client Secret	Yes	-
ATHENA_BASE_URL	athenahealth API Base URL	Yes	-
ATHENA_VERSION	API Version	No	v1
ATHENA_PRACTICE_ID	Practice ID	Yes	-
WEBHOOK_PORT	Webhook bridge server port (n8n mode)	No	3000
NODE_ENV	Environment	No	development
LOG_LEVEL	Log Level	No	info

athenahealth API Setup

1. Create Developer Account

   • Visit athenahealth Developer Portal
   • Create a developer account
   • Request sandbox access

2. Create API Application

   • Create a new application in the developer portal
   • Note down your Client ID and Client Secret
   • Configure OAuth 2.0 settings

3. Get Practice ID

   • Contact athenahealth support to get your Practice ID
   • This is required for API access

MCP Tools Reference

✅ Working in Sandbox (5 tools)

1. list_departments

Status: ✅ Fully Working Description: Lists all departments in the athenahealth practice

Parameters: None required

Example:

// List all departments
const departments = await mcpClient.callTool('list_departments', {});

---

2. list_providers

Status: ✅ Fully Working Description: Lists all healthcare providers in the practice

Parameters:

• name (optional) - Filter by provider name
• specialty (optional) - Filter by specialty
• limit (optional) - Maximum results (default: 50)

Example:

// List all providers
const providers = await mcpClient.callTool('list_providers', {
  specialty: 'Cardiology',
  limit: 20
});

---

3. search_patients

Status: ✅ Fully Working Description: Search for patients by name, DOB, phone, or email

Parameters (at least ONE required):

• firstname - Patient first name
• lastname - Patient last name
• dob - Date of birth (MM/DD/YYYY)
• phone - Phone number
• email - Email address
• limit (optional) - Maximum results (default: 10)

Example:

// Search for patients by name
const patients = await mcpClient.callTool('search_patients', {
  firstname: 'John',
  lastname: 'Smith',
  limit: 10
});

---

4. create_patient

Status: ✅ Fully Working Description: Register a new patient in the athenahealth system

Parameters (required):

• firstname - Patient first name
• lastname - Patient last name
• dob - Date of birth (MM/DD/YYYY)
• sex - Sex (M or F)
• department_id - Primary department ID

Parameters (optional):

• email, mobile_phone, home_phone, address1, city, state, zip
• guarantor_firstname, guarantor_lastname, guarantor_dob, guarantor_relationship

Important:

• ✅ Valid North American phone numbers required (not 555 area code)
• ✅ Date format: MM/DD/YYYY or YYYY-MM-DD

Example:

const patient = await mcpClient.callTool('create_patient', {
  firstname: 'John',
  lastname: 'Test',
  dob: '05/20/1985',
  sex: 'M',
  department_id: '1',
  email: 'john.test@example.com',
  mobile_phone: '6179876543',
  address1: '123 Main St',
  city: 'Boston',
  state: 'MA',
  zip: '02101'
});

---

5. check_appointment_availability

Status: ✅ Working (returns empty in sandbox) Description: Check available appointment slots for a department and date range

Parameters:

• department_id (required) - Department ID
• start_date (required) - Start date (YYYY-MM-DD)
• end_date (required) - End date (YYYY-MM-DD)
• provider_id (optional) - Specific provider ID
• appointment_type (optional) - Type of appointment

Note: Returns empty array in sandbox (no scheduling templates configured)

Example:

const availability = await mcpClient.callTool('check_appointment_availability', {
  department_id: '1',
  start_date: '2025-11-01',
  end_date: '2025-11-07',
  provider_id: '23'
});

---

❌ Not Working in Sandbox (8 tools)

These tools require production environment with full clinical access.

6. create_appointment

Status: ❌ Not Working - 404 Error Reason: Endpoint not available in sandbox, requires scheduling templates

7. check_drug_interactions

Status: ❌ Not Working - Tool Execution Failed Reason: Requires clinical endpoints and drug interaction database

8. get_clinical_summary

Status: ❌ Not Working - Clinical Endpoints Unavailable Reason: Clinical data endpoints (allergies, prescriptions, problems, vitals, labs, alerts) return 404

9. create_prescription

Status: ❌ Not Working - 404 Error Reason: E-prescribing endpoint not available in sandbox

10. get_patient_encounters

Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment

11. get_encounter

Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment

12. create_encounter

Status: ❌ Not Working - 404 Error Reason: Encounter creation requires production API with clinical documentation access

13. update_encounter

Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment

Note: See athenahealth-mcp-tools-readme.md for detailed information on production requirements for these tools.

---

MCP Prompts

clinical_assessment

Generate clinical assessment prompts with patient data

Parameters:

• patient_id (required)
• chief_complaint (optional)

medication_review

Generate medication review prompts (handles sandbox limitations gracefully)

Parameters:

• patient_id (required)

care_plan

Generate care plan development prompts

Parameters:

• patient_id (required)
• diagnosis (optional)

---

Working Sample Workflow (Sandbox)

// Step 1: List departments
const departments = await mcpClient.callTool('list_departments', {});
const departmentId = departments[0].departmentid;

// Step 2: Create a test patient
const patient = await mcpClient.callTool('create_patient', {
  firstname: 'John',
  lastname: 'Test',
  dob: '05/20/1985',
  sex: 'M',
  department_id: departmentId,
  email: 'john.test@example.com',
  mobile_phone: '6179876543',
  address1: '123 Main St',
  city: 'Boston',
  state: 'MA',
  zip: '02101'
});
// Returns: { patientid: "61378" }

// Step 3: Search for the patient
const searchResults = await mcpClient.callTool('search_patients', {
  lastname: 'Test',
  dob: '05/20/1985'
});

// Step 4: List providers
const providers = await mcpClient.callTool('list_providers', {
  specialty: 'Family Medicine'
});

---

⚠️ Important Notes

Sandbox vs Production

Sandbox Environment:

• ✅ Patient registration workflows
• ✅ Demographics and search
• ✅ Department and provider listing
• ✅ Appointment availability checking (returns empty)
• ❌ Clinical data (allergies, prescriptions, problems, vitals, labs)
• ❌ Encounter management (get, create, update)
• ❌ Appointment creation
• ❌ E-prescribing
• ❌ Drug interaction checking

Production Environment: Requires:

• Full athenahealth production API access
• Clinical endpoints enabled (allergies, prescriptions, problems, vitals, labs, alerts)
• Encounter documentation access
• E-prescribing licenses and integrations
• Scheduling templates configured
• Provider credentials (NPI, DEA numbers)
• HIPAA compliance measures

Phone Number Requirements

• ✅ MUST use valid North American area codes (617, 212, 415, etc.)
• ❌ CANNOT use 555 (reserved for fictional use)

Date Formats

• ✅ MM/DD/YYYY (e.g., 05/20/1985)
• ✅ YYYY-MM-DD (e.g., 1985-05-20)

---

Security and HIPAA Compliance

Data Protection

• All sensitive healthcare data is automatically sanitized in logs
• Patient identifiers are redacted in audit logs
• API communications use form-urlencoded for POST requests
• Access controls prevent unauthorized data access

Audit Logging

• All data access is logged with timestamps
• User actions are tracked for compliance
• Failed access attempts are recorded
• Audit logs are stored separately with extended retention

Best Practices

1. Environment Security: Store credentials in environment variables, never in code
2. Access Controls: Implement role-based access controls
3. Data Minimization: Only request necessary data
4. Regular Audits: Review audit logs regularly
5. Secure Deployment: Use secure deployment practices

---

API Rate Limits

athenahealth API has rate limits:

• Production: 1000 requests per minute
• Sandbox: 100 requests per minute

The server automatically handles rate limiting and implements exponential backoff for failed requests.

---

Error Handling

The server provides comprehensive error handling:

• Authentication Errors: Automatic token refresh
• API Errors: Structured error responses with details
• Network Errors: Retry logic with exponential backoff
• Validation Errors: Input validation with detailed messages
• Sandbox Limitations: Graceful handling with informative error messages

---

Development

Running in Development Mode

npm run dev

Running Tests

npm test

Build Project

npm run build

---

Architecture

The codebase is modularized for maintainability:

MCP Server Layer:

• src/mcp-server.ts - Main MCP server (323 lines)
• src/handlers/tool-handlers.ts - Tool implementations (635 lines)
• src/handlers/prompt-handlers.ts - Prompt generators (130 lines)
• src/handlers/resource-handlers.ts - Resource handlers (189 lines)
• src/definitions/tools.ts - Tool schemas (226 lines)

API Client Layer (Service-Oriented):

• src/services/athenahealth-client.ts - Unified client interface (130 lines)
• src/services/base-client.ts - Authentication & HTTP client (220 lines)
• src/services/patient-service.ts - Patient operations (130 lines)
• src/services/clinical-service.ts - Clinical data (160 lines)
• src/services/encounter-service.ts - Encounter management (100 lines)
• src/services/scheduling-service.ts - Appointments & providers (160 lines)

---

Documentation

• athenahealth-mcp-tools-readme.md - Complete tool reference guide
• athenahealth API Documentation - Official API docs
• Developer Portal - athenahealth developer resources

---

Support

For support and questions:

• Create an issue in the GitHub repository
• Review the comprehensive tool reference guide
• Contact athenahealth Developer Support: developer-support@athenahealth.com

---

Changelog

Version 1.2.0

• Added encounter management functionality (4 new tools: get_patient_encounters, get_encounter, create_encounter, update_encounter)
• Refactored athenahealth client into service-oriented architecture
  • Separated into base-client, patient-service, clinical-service, encounter-service, scheduling-service
  • Reduced file sizes from 800 lines to 100-220 lines per module
• Total tools increased from 9 to 13
• Documented encounter endpoints return 404 in sandbox (require production)
• Enhanced architecture documentation with service layer breakdown

Version 1.1.0

• Refactored codebase into modular architecture
• Fixed form-urlencoded POST request formatting for all endpoints
• Added graceful handling of sandbox limitations
• Enhanced medication_review prompt with sandbox support
• Improved error messages with detailed API responses
• Created comprehensive tool reference documentation

Version 1.0.0

• Initial release
• Basic MCP server implementation
• Patient data access
• Prescription management
• Clinical decision support prompts
• HIPAA-compliant logging
• OAuth 2.0 authentication

---

⚠️ Important: This software handles sensitive healthcare data. Ensure you comply with all applicable healthcare regulations including HIPAA, HITECH, and other relevant standards in your jurisdiction.

📖 For detailed tool specifications and production requirements, see athenahealth-mcp-tools-readme.md