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.demo.healthex.dev/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, labs, procedures, visits, and immunizations

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)

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)

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.

get_procedures​

Get Procedures

Retrieve medical procedures including surgeries, diagnostic procedures (endoscopy, colonoscopy), imaging studies, 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)

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)

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)

Search & Discovery​

search_records​

Search Health Records

Search across all health record categories using keywords or phrases. Searches through conditions, medications, lab results, procedures, clinical visits, clinical notes, and imaging results. Returns matching records with context.

Use cases:

  • Looking for specific terms across all records
  • Exploratory searches when unsure which category to check
  • Finding all mentions of a specific condition, medication, or test

Parameters:

  • query (required, string): Search term or phrase to find across health records

check_recent_records​

Check Recent Health Records

Returns the last date that any health records were connected and provides the URL to update 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, 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 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 })

Pagination​

The get_labs and get_medications 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