Skip to main content

MCP Server Tools

HealthEx provides a comprehensive suite of read-only tools for accessing and analyzing patient health records through the Model Context Protocol (MCP). All tools are designed with patient safety and data privacy in mind.

Installing the MCP Server​

  • MCP Server URL: https://api.healthex.io/mcp

Tool Characteristics​

  • Read-only access: All tools are readOnlyHint=true and destructiveHint=false
  • Default time range: Returns 3 years of history by default, with date parameters available for customization
  • Chronological ordering: Results are sorted chronologically (most recent first) unless otherwise specified
  • Comprehensive coverage: Access to conditions, medications, allergies, labs, vitals, procedures, visits, immunizations, and clinical notes.

Available Tools​

Core Health Overview​

get_health_summary​

Get Health Summary

Retrieve a comprehensive current health snapshot including age, date of birth, gender, active medical conditions, current medications with dosages, allergies with reaction types, most recent vital signs (blood pressure, weight, height, BMI, heart rate), last visit date, and primary care provider.

Use cases:

  • First tool to call for general health questions
  • Quick assessment of overall health status
  • Combined with conditions, labs, immunizations, and visits for preventive care screening recommendations and care gap identification

Parameters: None

get_conditions​

Get Conditions

Retrieve all medical conditions with start dates and end dates (for resolved, treated, or inactive conditions). Returns a chronological list of diagnoses and current health concerns.

Use cases:

  • Answering "Have I ever had X?" questions
  • Understanding complete medical history
  • Tracking how health status has changed over time

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

get_medications​

Get Medications

Access detailed medication information including complete dosing instructions, prescribing provider, indication, start date, pharmacy information, refill history, medication changes over time, discontinuation dates and reasons, and notes about side effects or adjustments.

Use cases:

  • Detailed questions about medications beyond basic active medication list
  • Understanding medication changes and adjustments over time
  • Reviewing refill history and adherence patterns

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

get_allergies​

Get Allergies

Retrieve patient allergy and intolerance information including allergen name, clinical status (active, inactive, resolved), verification status, type (allergy, intolerance), criticality (low, high, unable-to-assess), onset date or age, and documented reactions. Returns allergies ordered by date (most recent first).

Use cases:

  • Reviewing complete allergy history before prescribing medications
  • Understanding allergic reactions and their severity
  • Checking for drug allergies during medication reconciliation
  • Identifying food allergies or environmental sensitivities

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

Diagnostic Results​

get_labs​

Get Lab Results

Access laboratory test results including test name, value with units, reference range, date performed, ordering provider, and abnormal flags. Covers blood work, urinalysis, and pathology results.

Use cases:

  • Questions about specific lab values
  • Tracking lab value trends over time
  • Reviewing recent lab results

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data. Vital signs are excluded from this tool and available via get_vitals.

get_vitals​

Get Vital Signs

Access vital sign measurements including blood pressure (systolic/diastolic), heart rate, body temperature, respiratory rate, oxygen saturation (SpO2), weight, height, and BMI. Returns measurement values with units, dates, reference ranges, and abnormal flags.

Use cases:

  • Tracking vital sign trends over time
  • Monitoring blood pressure, weight, or other vitals
  • Understanding changes in vital measurements
  • Reviewing vital signs from specific time periods

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available
  • vitals (optional, array): Specific vital types to retrieve. If not specified, returns all vital types. Options: "Blood Pressure", "Heart Rate", "Body Temperature", "Respiratory Rate", "Oxygen Saturation", "Weight", "Height", "Body Mass Index"

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

get_procedures​

Get Procedures

Retrieve medical procedures including surgeries, diagnostic procedures (endoscopy, colonoscopy), biopsies, and interventions. Returns procedure name, date, location, performing provider, indication, and outcomes.

Use cases:

  • Understanding surgical history
  • Reviewing diagnostic workup
  • Determining when screenings were last performed

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

Preventive Care​

get_immunizations​

Get Immunizations

Access complete vaccination history including vaccine name, date administered, dose number, series completion status, and administering provider. Covers childhood vaccines, flu shots, COVID-19, travel vaccines, and boosters.

Use cases:

  • Travel planning and requirements
  • Work or school vaccination requirements
  • Preventive care assessment

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

Care History​

get_visits​

Get Clinical Visits

Retrieve complete clinical visit history including visit date, visit type (ambulatory in-person, ambulatory telehealth, inpatient, ER), provider name, location, chief complaint, and diagnoses addressed.

Use cases:

  • Understanding clinical care patterns
  • Identifying follow-up patterns
  • Finding frequently visited providers and health system locations
  • Identifying nearby care resources based on established care patterns

Parameters:

  • years (optional, number): Number of years of history to retrieve (default: 3)
  • beforeDate (optional, string): End date for query (ISO 8601: YYYY-MM-DD) for pagination when previous response indicates more data available

Note: Results are paginated. Check response metadata for hasMoreData flag and use beforeDate parameter for retrieving additional historical data.

get_notes_by_visit​

Deprecated: Use search_clinical_notes instead.

Get Clinical Notes by Visit

Get all clinical notes and documentation for exactly one specific visit. Returns the complete visit record along with all associated clinical documentation, including clinical notes, progress notes, discharge summaries, and narrative text. You must obtain a valid encounterId before calling this tool. If the encounterId is not already known, first call get_visits to identify the correct visit (by date, type, or context).

Use cases:

  • Deep understanding of the clinical care provided during a specific visit

Parameters:

  • encounterId (required, string): The encounterId from the encounterId column in the get_visits tool response. Example: "eTOpusRp6P4wuw-OP2xdr0g3"

search_clinical_notes​

Search Clinical Notes

Search across all clinical notes for specific keywords or phrases. Searches through progress notes, clinical documentation, discharge summaries, and other narrative text from all visits. Use this to find mentions of specific symptoms, treatments, discussions, or clinical findings across the patient's entire record. Uses keyword search first for exact text matching, and automatically falls back to AI-powered semantic search if no keyword matches are found (e.g., searching "heart attack" can find "myocardial infarction").

Use cases:

  • Finding all mentions of a specific symptom or condition across visits
  • Searching for treatment discussions or clinical recommendations
  • Locating notes about specific procedures or medications
  • Cross-visit analysis of clinical documentation
  • Finding conceptually related content via automatic semantic fallback

Parameters:

  • query (required, string): The keyword or phrase to search for in clinical notes. Examples: "chest pain", "diabetes management", "surgical history"
  • years (optional, number): Number of years of history to search (default: 3)
  • beforeDate (optional, string): End date for the search (ISO 8601: YYYY-MM-DD). Defaults to today.

Search & Discovery​

Search Health Records

Semantically search across all patient health record categories using natural language queries. Searches through conditions, medications, lab results, procedures, clinical visits, and clinical notes. Returns matching records with context and relevance scores.

Use cases:

  • Exploratory searches when unsure which specific category or tool to query
  • Fallback when other specific tools don't return expected results
  • Finding mentions of specific terms, conditions, medications, or tests across all record types
  • Natural language queries about patient health information

Parameters:

  • query (required, string): Natural language query string to search for across health records

update_and_check_recent_records​

Check Recent Health Records

Check when health records were last updated and get a link to update them. Returns the last update date, whether records are currently being updated, and a URL where users can update or reconnect their health records on HealthEx.

Use cases:

  • Verifying data recency
  • Directing users to update their health records
  • Understanding data freshness for clinical decision support

Parameters: None

Usage Guidelines​

Best Practices​

  1. Start with get_health_summary: For general health questions, always begin with the health summary to get a comprehensive overview
  2. Use specific tools for detailed queries: Follow up with targeted tools (labs, vitals, medications, conditions) when users need detailed information
  3. Leverage search for exploratory queries: Use search_records when uncertain which category contains the relevant information
  4. Check data recency: Use update_and_check_recent_records to verify when data was last updated, especially for time-sensitive clinical decisions
  5. Combine tools for comprehensive analysis: Use multiple tools together for preventive care recommendations (e.g., health summary + conditions + labs + immunizations + visits)

Time Range Customization​

All tools support the years parameter to customize the historical data range:

// Get 5 years of lab history instead of default 3
get_labs({ years: 5 })

// Get complete immunization history
get_immunizations({ years: 50 })

// Get recent medication changes only
get_medications({ years: 1 })

// Get only blood pressure and weight readings
get_vitals({ vitals: ["Blood Pressure", "Weight"] })

Pagination​

Many tools implement pagination to manage large result sets:

  • Check the hasMoreData flag in response metadata
  • Use the beforeDate parameter from previous response to fetch earlier data
  • Note: hasMoreData: false only means no more data in the requested range, not that no historical data exists

Data Privacy & Security​

  • All tools are read-only and cannot modify patient data
  • Tools only access data for the authenticated user
  • All data transmission is encrypted
  • Tools respect patient consent and data sharing preferences

Support​

For issues or questions, please contact support@healthex.io