Athena Health MCP Server

Athena Health MCP Server

A Model Context Protocol (MCP) server for integrating with Athena Health's API to manage appointments, providers, departments, and patient data.

Overview

This MCP server provides tools for:

• Appointment management (create, update, cancel, view)
• Provider and department information
• Patient search functionality
• Available appointment slot discovery

Setup

Prerequisites

1. Python 3.8+
2. Required environment variables:
   • ATHENA_CLIENT_ID: Your Athena Health API client ID
   • ATHENA_CLIENT_SECRET: Your Athena Health API client secret
   • ATHENA_PRACTICE_ID: Your practice ID
   • ATHENA_BASE_URL: (Optional) API base URL (defaults to production)

Installation

1. Install dependencies:

2. Set environment variables:

3. Run the server:

Available Tools

1. get_appointments

Retrieve appointments for a specific date range with optional filtering.

Parameters:

• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format
• provider_id (optional): Provider ID to filter appointments
• department_id (optional): Department ID to filter appointments

Example:

2. get_available_slots

Get available appointment slots for scheduling.

Parameters:

• provider_id (required): Provider ID
• department_id (required): Department ID
• appointment_type_id (required): Appointment type ID
• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format

Example:

3. create_appointment

Create a new appointment.

Parameters:

• patient_id (required): Patient ID
• provider_id (required): Provider ID
• department_id (required): Department ID
• appointment_type_id (required): Appointment type ID
• appointment_date (required): Appointment date in YYYY-MM-DD format
• appointment_time (required): Appointment time in HH format
• reason_for_visit (optional): Reason for the visit

Example:

4. update_appointment

Update an existing appointment.

Parameters:

• appointment_id (required): Appointment ID to update
• appointment_date (optional): New appointment date in YYYY-MM-DD format
• appointment_time (optional): New appointment time in HH format
• reason_for_visit (optional): Updated reason for the visit
• notes (optional): Additional notes

Example:

5. cancel_appointment

Cancel an appointment.

Parameters:

• appointment_id (required): Appointment ID to cancel
• cancellation_reason (optional): Reason for cancellation

Example:

6. get_providers

Get list of providers with optional filtering.

Parameters:

• department_id (optional): Department ID to filter providers
• specialty (optional): Specialty to filter providers

Example:

7. get_departments

Get list of all departments.

Parameters: None

Example:

8. get_appointment_types

Get available appointment types with optional filtering.

Parameters:

• department_id (optional): Department ID to filter appointment types
• provider_id (optional): Provider ID to filter appointment types

Example:

9. search_patients

Search for patients by various criteria.

Parameters:

• first_name (optional): Patient first name
• last_name (optional): Patient last name
• date_of_birth (optional): Date of birth in YYYY-MM-DD format
• phone (optional): Phone number
• email (optional): Email address

Example:

API Endpoints

The server interacts with the following Athena Health API endpoints:

• POST /oauth2/v1/token - Authentication
• GET /v1/{practice_id}/appointments - Get appointments
• GET /v1/{practice_id}/appointments/open - Get available slots
• POST /v1/{practice_id}/appointments - Create appointment
• PUT /v1/{practice_id}/appointments/{id} - Update appointment
• GET /v1/{practice_id}/providers - Get providers
• GET /v1/{practice_id}/departments - Get departments
• GET /v1/{practice_id}/appointmenttypes - Get appointment types
• GET /v1/{practice_id}/patients - Search patients

Authentication

The server automatically handles OAuth2 authentication using client credentials flow. Tokens are cached and refreshed as needed.

Error Handling

The server includes comprehensive error handling for:

• Authentication failures
• API request failures
• Invalid parameters
• Network errors

All errors are logged and returned as part of the tool response.

Usage Examples

Complete Workflow Example

1. Get departments:

2. Get providers in a department:

3. Get appointment types:

4. Search for available slots:

5. Search for a patient:

6. Create an appointment:

Response Format

All tool responses are returned as JSON strings containing the API response data. For example:

Troubleshooting

Common Issues

1. Authentication Errors:
   • Verify your ATHENA_CLIENT_ID and ATHENA_CLIENT_SECRET are correct
   • Ensure your API credentials have the necessary permissions
2. Missing Environment Variables:
   • The server will exit with an error message listing missing variables
   • Set all required environment variables before running
3. API Request Failures:
   • Check that your ATHENA_PRACTICE_ID is correct
   • Verify the API endpoints are accessible from your network
   • Review the error response for specific API error messages

Logging

The server logs all operations at INFO level. Check the console output for detailed information about:

• Authentication attempts
• API requests and responses
• Error details

Security Considerations

• Never commit API credentials to version control
• Use environment variables for all sensitive configuration
• The server automatically handles token refresh and secure storage
• All API communication uses HTTPS

Support

For issues with the MCP server implementation, check the logs for detailed error messages. For Athena Health API-specific issues, refer to the official Athena Health API documentation. # athenahealth-mcp