MCP Server Tools

HealthEx provides a comprehensive suite of tools for accessing and analyzing patient health records through the Model Context Protocol (MCP). Most tools are read-only queries; one tool (update_records) requests a server-side background refresh of connected records. 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 by default: Clinical data tools are readOnlyHint=true and destructiveHint=false. The update_records tool is not read-only: it triggers (or attempts to trigger) a background data refresh and is subject to per-patient rate limits.
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 with encounterId parameter 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 or Retrieve Clinical Notes

This tool supports two modes of operation:

Search Mode: 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. 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").
Encounter Mode: Retrieve all clinical notes for a specific visit/encounter. Use get_visits first to find the encounter ID, then pass it to get all notes associated with that visit.

Use cases:

Finding all mentions of a specific symptom or condition across visits (Search Mode)
Searching for treatment discussions or clinical recommendations (Search Mode)
Locating notes about specific procedures or medications (Search Mode)
Cross-visit analysis of clinical documentation (Search Mode)
Finding conceptually related content via automatic semantic fallback (Search Mode)
Retrieving all clinical documentation for a specific visit (Encounter Mode)
Deep understanding of clinical care provided during a specific visit (Encounter Mode)

Parameters:

query (optional, string): The keyword or phrase to search for in clinical notes. Examples: "chest pain", "diabetes management", "surgical history". Required if encounterId is not provided.
encounterId (optional, string): The encounter/visit ID to retrieve all clinical notes for. Get this ID from the get_visits tool. Required if query is not provided.
years (optional, number): Number of years of history to search (default: 3). Only used with query parameter.
beforeDate (optional, string): End date for the search (ISO 8601: YYYY-MM-DD). Defaults to today. Only used with query parameter.

Note: Either query or encounterId must be provided. If both are provided, encounterId takes precedence.

Search & Discovery

`search`

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

Record sync & refresh

`update_records`

Update Health Records

Requests a background refresh of health records from connected locations. The response includes a status and human-readable message. It does not include when records were last successfully finalized (use check_records_status for that).

Possible status values:

Status	Meaning
`UPDATE_IN_PROGRESS`	A refresh is already running.
`UPDATE_STARTED`	New retrieval work was started; may take minutes to complete.
`PARTIAL_UPDATE`	Refresh started but some locations could not be reached (sessions may have expired); includes `reconnectUrl` for those locations.
`THROTTLED`	The limit of 2 MCP-initiated refresh requests per patient per day was reached; includes `dailyLimit`, `refreshesRemaining`, and `reconnectUrl` for manual refresh.
`ACTION_NEEDED`	All locations failed, none are connected, or consent has been revoked/expired; the patient must open the returned `reconnectUrl` to re-authenticate, connect locations, or re-grant consent.

Use cases:

Prompting a background sync after the patient has connected sources
Recovering when data may be stale (subject to rate limits)

Parameters: None

Notes:

Limited to 2 MCP-initiated refresh requests per patient per day.
Not a substitute for checking last sync time; pair with check_records_status when you need timestamps.

`check_records_status`

Check Health Records Status

Returns the current sync status of health records. This is a read-only operation that does not trigger a refresh.

Response:

Response	Meaning
`{ "updateInProgress": true }`	A refresh is currently in progress.
`{ "lastUpdated": "<ISO timestamp>" }`	Timestamp of last successful sync.
`{ "lastUpdated": null }`	Records have never been synced.

Use cases:

Checking data recency before answering time-sensitive questions
Verifying no refresh is running before calling update_records

Parameters: None

`update_and_check_recent_records`

Deprecated

This tool is deprecated. Prefer:

check_records_status — sync status (lastUpdated or in-progress only, not both).
update_records — request a background refresh (may be throttled; see above).

The legacy tool remains available for backward compatibility. It performs a read-only check: human-readable message, optional lastUpdated, and reconnectUrl when not in progress. It does not start a refresh or affect throttle counts.

Legacy title: Update and Check Recent Health Records

Use cases (legacy): Same as checking recency and linking users to reconnect flows; new integrations should use the two tools above.

Parameters: None

Usage Guidelines

Best Practices

Start with get_health_summary: For general health questions, always begin with the health summary to get a comprehensive overview
Use specific tools for detailed queries: Follow up with targeted tools (labs, vitals, medications, conditions) when users need detailed information
Leverage search for exploratory queries: Use search when uncertain which category contains the relevant information
Check data recency: Use check_records_status — it returns either lastUpdated (when idle) or updateInProgress: true (when a refresh is running), not both; use update_records when a new background refresh is appropriate (respecting rate limits)
Combine tools for comprehensive analysis: Use multiple tools together for preventive care recommendations (e.g., health summary + conditions + labs + immunizations + visits)

Time Range Customization

Clinical history tools (conditions, labs, medications, etc.) 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

Clinical query tools are read-only and do not edit medical record content; update_records requests a server-orchestrated refresh from connected sources (it does not let the model arbitrarily change stored records)
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

Installing the MCP Server​

Tool Characteristics​

Available Tools​

Core Health Overview​

get_health_summary​

get_conditions​

get_medications​

get_allergies​

Diagnostic Results​

get_labs​

get_vitals​

get_procedures​

Preventive Care​

get_immunizations​

Care History​

get_visits​

get_notes_by_visit​

search_clinical_notes​

Search & Discovery​

search​

Record sync & refresh​

update_records​

check_records_status​

update_and_check_recent_records​

Usage Guidelines​

Best Practices​

Time Range Customization​

Pagination​

Data Privacy & Security​

Support​

Installing the MCP Server

Tool Characteristics

Available Tools

Core Health Overview

`get_health_summary`

`get_conditions`

`get_medications`

`get_allergies`

Diagnostic Results

`get_labs`

`get_vitals`

`get_procedures`

Preventive Care

`get_immunizations`

Care History

`get_visits`

`get_notes_by_visit`

`search_clinical_notes`

Search & Discovery

`search`

Record sync & refresh

`update_records`

`check_records_status`

`update_and_check_recent_records`

Usage Guidelines

Best Practices

Time Range Customization

Pagination

Data Privacy & Security

Support