CharmHealth

CharmHealth MCP Server

An MCP server for CharmHealth EHR that allows LLMs and MCP clients to interact with patient records, encounters, and practice information.

What is an MCP Server?

MCP Info

Image Building Info

Available Tools (17)

Tools Details

Tool: findPatients

Find patients.

Complex searches: Use search_type="advanced" with multiple criteria:

• Age ranges: age_min=65, age_max=80 for elderly patients
• Location: state="CA", city="Los Angeles" for geographic filtering
• Medical: blood_group="O+", language="Spanish" for clinical needs

Always returns patient_id needed for other tools. Start here before any patient operations.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: getPracticeInfo

Get practice information.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: manageAppointments

Manage appointments.

Time format: Use 12-hour format like "09:30 AM" or "02:15 PM" For recurring: Set repetition to "Weekly" or "Daily" and provide frequency + end_date For double booking: Use provider_double_booking="allow" or resource_double_booking="allow" to override checks For cancellation: Use delete_type "Current" for single appointment or "Entire" for recurring series

List filters (applied after fetching all appointments in the date range):

• status_filter: e.g., status_filter="Confirmed"
• provider_filter: provider_id or provider_name substring (e.g., provider_filter="12345" or provider_filter="Smith")
• mode_filter: e.g., mode_filter="Video Consult"
• limit: e.g., limit=25

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: manageEncounter

Manage encounters.

For creating encounters (two paths):

• From appointment: patient_id + appointment_id (provider/facility/date come from the appointment)
• From scratch: patient_id + provider_id + facility_id + encounter_date
• Optional: visit_type_id, encounter_mode, chief_complaint

For reviewing encounters:

• Requires: patient_id, encounter_id
• Shows comprehensive encounter details including vitals, diagnoses, medications, notes

For signing encounters:

• Requires: patient_id, encounter_id
• Only use after reviewing and confirming all information is accurate

For unlocking encounters:

• Requires: patient_id, encounter_id, reason
• Used to unlock signed encounters when modifications are needed
• Must provide a valid reason for unlocking the encounter

For updating encounters with template data:

• action="update" with chief_complaint always saved as narrative fallback
• template_ids: comma-separated IDs of templates to attach to the encounter
• entries: JSON array string of populated template entries, e.g. '[{"entry_id":"123","answer":"text"}]'
• Templates are attached first, then entries + chief_complaints saved together
• entry_id values must come from getPracticeInfo(info_type='template_details') — hallucinated IDs are dropped client-side

Recommended workflow:

1. Create encounter: manageEncounter(patient_id, appointment_id, action="create") — or without appointment: manageEncounter(patient_id, provider_id, facility_id, encounter_date, action="create")
2. Add clinical data using managePatientVitals(), managePatientDrugs(), managePatientDiagnoses()
3. Review before signing: manageEncounter(patient_id, encounter_id, action="review")
4. Sign to finalize: manageEncounter(patient_id, encounter_id, action="sign")
5. If modifications needed: manageEncounter(patient_id, encounter_id, reason="reason for changes", action="unlock")

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: manageFax

Send faxes and check fax delivery status.

• "status": Check fax delivery status (requires fax_id). Status values: QUEUED, SENT, FAILED, YET_TO_SEND.

Common fax use cases:

• Referral letters to specialists
• Medical records requests
• Prior authorization forms to insurance
• Prescription orders to pharmacies without e-prescribe </instructions>

Tool: manageMessages

Manage patient and provider messaging across SMS, WhatsApp, and secure messaging channels.

• "list": Show recent secure portal messages from inbox. Filter by section: "FROM_PATIENTS" (inbox) or "TO_PATIENTS" (sent). Use facility_id to filter by facility. Note: SMS and WhatsApp conversations are not available via list — use action='get_thread' with a patient_id to retrieve those.

• "get_thread": Get full conversation history with a specific patient (requires patient_id). Filter by thread_channel to see only SMS, WhatsApp, secure, or all channels.

Before sending clinical content, confirm with the provider. Routine messages (appointment reminders, general notifications) can be sent directly. </instructions>

Tool: managePatient

Manage patients.

Update Modes:

• update_specific_details=True: Only updates the fields you provide, preserves all other existing data (RECOMMENDED, Default)
• update_specific_details=False: Complete record update - must provide all fields or existing data will be lost

Demographics: Supports comprehensive patient information including social history, family data Addresses: If any address field provided, country is required (defaults to US) Facilities: Pass as list of facility IDs like "facility_123,facility_456". Categories: Pass as list like [{"category_id": "category_123"}]

Complex Relationships:

• caregivers: [{"first_name": str, "last_name": str, "relationship": str, "contact": {...}, "address": {...}}]
• guarantor: [{"first_name": str, "last_name": str, "relationship": str, "contact": {...}, "address": {...}}]
• id_qualifiers: [{"id_qualifier": 1-8 or 99, "id_of_patient": "ID_value"}]

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientAllergies

Manage patient allergies.

Safety critical: Always check allergies before prescribing medications. Common allergens: "Penicillin", "Latex", "Shellfish", "Nuts", "Contrast dye" Severity levels: "Mild", "Moderate", "Severe" Allergy types: "Medication", "Drug Substance", "Environmental", "Food", "Plant", "Animal", "Latex" Status values: "Active", "Inactive"

List filters:

• severity_filter: e.g., severity_filter="Severe"
• type_filter: e.g., type_filter="Drug"
• limit: e.g., limit=50

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientDiagnoses

Manage patient diagnoses.

Code types: "ICD10", "SNOMED" Status options: "Active", "Inactive", "Resolved" List filters:

• status_filter: filter by diagnosis_status (e.g., status_filter="Active")
• code_type_filter: filter by code_type (e.g., code_type_filter="ICD10")
• from_date / to_date: best-effort date filtering (e.g., from_date="2025-01-01", to_date="2025-12-31")
• limit: e.g., limit=25 Use encounter_id to link diagnosis to specific visit for billing and documentation

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientDrugs

Manage patient drugs and supplements.

Substance Types:

• "medication": Prescription drugs (requires directions, refills)
• "supplement": OTC supplements/vitamins (requires dosage as integer)
• "vitamin": Specific vitamins (requires dosage as integer)

Safety: Automatically checks allergies before prescribing unless check_allergies=False List filters:

• status_filter: e.g., status_filter="active"
• limit: e.g., limit=25 For medications: Use clear directions like "Take 1 tablet by mouth twice daily with food" For supplements: Provide dosage as integer (e.g., 5) and use strength for units (e.g., "500mg")

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientFiles

Manage patient files and documents.

ID Qualifiers: military_id, state_issued_id, drivers_license_id, passport_id, social_security_number, etc. File paths should be absolute paths to image/PDF files on the system.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientLabs

Manage patient laboratory results.

List filters (in addition to API parameters):

• status_filter: 0 (pending) or 2 (final)
• from_date / to_date: e.g., from_date="2025-01-01", to_date="2025-12-31" (best-effort against common date fields)
• limit: e.g., limit=50

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientNotes

Manage patient notes.

Use for: Important care instructions, provider alerts, patient preferences, social determinants Formal encounter notes should use manageEncounter() instead

List filters:

• from_date / to_date: e.g., from_date="2025-01-01", to_date="2025-12-31"
• limit: e.g., limit=50

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientRecalls

Manage patient recalls.

recall_type is a free-form string set by the practice (e.g. "Office Visit", "Follow-up", "Imaging", "Annual Physical"). Do not invent verbose names — use short descriptive terms. Scheduling: PREFER recall_date (ISO date string, e.g. "2026-07-10"). If using recall_time/recall_timeunit instead, recall_period is also REQUIRED (e.g. recall_time=3, recall_timeunit="Months", recall_period="after") — omitting recall_period causes a server error. Reminder timing: email_reminder_before/text_reminder_before in days (e.g., 7 for one week) Use getPracticeInfo() to get valid provider_id and facility_id values

List filters:

• type_filter: e.g., type_filter="Annual Physical"
• from_date / to_date: e.g., from_date="2025-01-01", to_date="2025-12-31" (compares against recall_date when available)
• limit: e.g., limit=25

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: managePatientVitals

Manage patient vitals and vital signs.

Vitals Format:

• As dict: keys are EXACT CharmHealth vital names, values are "value unit" strings. Example: {"Systolic BP": "120 mmHg", "Diastolic BP": "80 mmHg", "Weight": "150 lbs", "Temp": "98 F"}
• Individual: vital_name="Systolic BP", vital_value="120", vital_unit="mmHg"

IMPORTANT: vital_name must be the exact CharmHealth API name. NEVER include units inside the name. Correct: "Systolic BP" | Wrong: "Systolic BP (mmHg)" or "Blood Pressure" Known names: Weight, Height, BMI, Temp, Systolic BP, Diastolic BP, Pulse Rate, Pulse Pattern, Pulse Volume, Vision Call getPracticeInfo(info_type='vitals') to get the full list of valid names and units for this practice.

List filters:

• vital_name_filter: e.g., vital_name_filter="Blood Pressure" (matches case-insensitively, substring ok)
• from_date / to_date: e.g., from_date="2025-01-01", to_date="2025-12-31"
• limit: e.g., limit=20

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Tool: manageTasks

Manage CharmHealth tasks.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

List filters:

• status_filter: filter by status (e.g., status_filter="Pending")
• priority_filter: "0"-"3" or "Low"/"Medium"/"High"/"Critical"
• owner_filter: filter by owner_id
• limit: max tasks to return (applied after filtering)

Examples:

• manageTasks(action="list", view="MyTasks", status_filter="In-progress", limit=20)
• manageTasks(action="list", view="All", priority_filter="High", owner_filter="12345") </instructions>

Tool: reviewPatientHistory

Review patient history.

Optional filters (apply to specific sections):

• diagnosis_status_filter: filter diagnoses by status (e.g., diagnosis_status_filter="Active")
• medication_status_filter: filter medications by status (e.g., medication_status_filter="active")
• supplement_status_filter: filter supplements by status (e.g., supplement_status_filter="active")
• vitals_limit: limit number of vital entries returned (e.g., vitals_limit=10)
• encounters_limit: limit number of encounters returned (e.g., encounters_limit=5)

For each filtered section, the response includes <section>_total_count and <section>_filtered_count.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values. </instructions>

Use this MCP Server

{
  "mcpServers": {
    "charmhealth-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CHARMHEALTH_BASE_URL",
        "-e",
        "CHARMHEALTH_CLIENT_ID",
        "-e",
        "CHARMHEALTH_CLIENT_SECRET",
        "-e",
        "CHARMHEALTH_REDIRECT_URI",
        "-e",
        "CHARMHEALTH_TOKEN_URL",
        "-e",
        "CHARMHEALTH_API_KEY",
        "-e",
        "CHARMHEALTH_REFRESH_TOKEN",
        "mcp/charmhealth-mcp-server"
      ],
      "env": {
        "CHARMHEALTH_BASE_URL": "your_base_url_here",
        "CHARMHEALTH_CLIENT_ID": "your_client_id_here",
        "CHARMHEALTH_CLIENT_SECRET": "your_client_secret_here",
        "CHARMHEALTH_REDIRECT_URI": "your_redirect_uri_here",
        "CHARMHEALTH_TOKEN_URL": "your_token_url_here",
        "CHARMHEALTH_API_KEY": "<CHARMHEALTH_API_KEY>",
        "CHARMHEALTH_REFRESH_TOKEN": "<CHARMHEALTH_REFRESH_TOKEN>"
      }
    }
  }
}

Why is it safer to run MCP Servers with Docker?