# Epic Fhir MCP

> Epic Fhir provides direct access to Epic's FHIR R4 clinical data. Query patient records by name, date of birth, or medical record number, pulling everything from encounters and lab reports to medications and allergies—all through natural conversation with your AI agent.

## Overview
- **Category:** data-management
- **Price:** Free
- **Tags:** electronic-health-records, fhir-r4, patient-data, clinical-observations, lab-results, ehr-integration

## Description

Connecting clinical data used to treat over 305 million patients worldwide is complicated. Usually, you're stuck clicking between dozens of tabs just to build a patient timeline. This MCP changes that. You can talk to it like talking to a nurse; tell your agent exactly what you need—like 'What were the diagnoses and medications after his ER visit?' The system pulls all those disparate data points together instantly. Because this connector is managed by Vinkius, you just connect once from any compatible client and get access to the entire catalog of clinical services. You can pull lab results, review a patient’s full history, check immunizations, or list active conditions without ever having to navigate a complex EHR interface. It's about getting the answer, not mastering the system.

## Tools

### search_patients
Searches the patient database to find records using name, date of birth, or medical record number.

### list_immunizations
Provides a vaccination history, including vaccine type, administration date, dose amount, and lot number.

### get_patient
Retrieves basic identifying information for a specific patient, including phone, email, address, and identifiers.

### list_encounters
Lists all patient visits or encounters, providing details on the type of visit, location, and time period.

### list_observations
Retrieves clinical observations—like blood work or vital signs—filterable by category and including reference ranges.

### list_conditions
Lists active or resolved medical diagnoses and conditions using ICD-10 codes and onset dates.

### list_medications
Lists all medications associated with the patient, noting dosage, frequency, prescriber, and current status.

### list_allergies
Lists all recorded allergies and intolerances, detailing the substance and severity of reactions.

### list_appointments
Checks a patient's scheduled appointments, including date/time, provider, location, and status.

### list_diagnostic_reports
Retrieves specific diagnostic reports, including the conclusion and results from performing organizations.

## Prompt Examples

**Prompt:** 
```
Find all patients named Smith born in 1985.
```

**Response:** 
```
Found 3 patients matching 'Smith' born in 1985:
1. John Smith (ID: e63wACU8F) — DOB: 1985-03-12, Male, MRN: 203847
2. Sarah Smith (ID: TnOZ.mfU4) — DOB: 1985-09-28, Female, MRN: 410293
3. Robert Smith (ID: eAr3bA.mH) — DOB: 1985-01-05, Male, MRN: 587102
Would you like to see the full medical history for any of these patients?
```

**Prompt:** 
```
Show me the latest lab results for patient e63wACU8F.
```

**Response:** 
```
Lab results for John Smith (last 30 days):
• Hemoglobin A1c: 6.2% (ref: <5.7% normal, 5.7-6.4% prediabetes) ⚠️
• Glucose (fasting): 118 mg/dL (ref: 70-100) ⚠️
• Creatinine: 0.9 mg/dL (ref: 0.7-1.3) ✓
• eGFR: 92 mL/min (ref: >60) ✓
• Total Cholesterol: 198 mg/dL (ref: <200) ✓
The A1c and fasting glucose are slightly elevated, suggesting prediabetic range. Want me to check current medications and conditions?
```

**Prompt:** 
```
List all active medications for this patient.
```

**Response:** 
```
Active medications for John Smith:
1. Metformin 500mg — 1 tablet twice daily with meals (Dr. Chen, prescribed 2024-11-15)
2. Lisinopril 10mg — 1 tablet daily (Dr. Chen, prescribed 2024-06-02)
3. Atorvastatin 20mg — 1 tablet at bedtime (Dr. Patel, prescribed 2024-03-10)
No known allergies documented. Want me to check the immunization record or upcoming appointments?
```

## Capabilities

### Search for patients
Find specific patient records using name, date of birth, or medical record number.

### Build a full medical timeline
Gather all past hospital visits and outpatient appointments to track a patient's care journey over time.

### Analyze lab data trends
Pull observations, including blood work and vital signs, and compare them against standard reference ranges.

### Review current medical status
View a patient's active medications, dosages, and known allergies in one place.

### Synthesize clinical history
Combine diagnoses, encounters, and lab results to give a complete picture of the patient’s health status.

## Use Cases

### The admitting nurse needs a rapid history review.
A nurse gets a new admission and needs a quick status update. They tell their agent, 'What are all active medications and diagnoses for this patient?' The agent uses `list_medications` and `list_conditions`, providing the nurse with an instant summary they can use at the bedside.

### The specialist needs to check compliance.
A specialist is reviewing a follow-up visit. They ask their agent, 'Show me all immunizations and appointments for the last year.' The agent uses `list_immunizations` and `list_appointments`, ensuring the patient's vaccination status is up to date.

### The research team needs data points.
A clinical researcher wants a cohort of patients who had specific issues. They ask their agent, 'Find all patients with condition X and whose lab results show high glucose.' The agent uses `search_patients` and then filters using `list_observations`.

### The care manager needs to review risks.
A care manager is preparing for a discharge. They ask their agent, 'What are the current allergies, medications, and diagnostic reports?' The agent runs `list_allergies`, `list_medications`, and `list_diagnostic_reports` sequentially to build a risk summary.

## Benefits

- Stop searching through separate systems. You can pull medication lists and check active conditions using the `list_medications` and `list_conditions` tools in one go.
- Build a complete care narrative by combining data from multiple sources, like checking past `list_encounters` alongside current lab results from `list_observations`.
- Never miss a vaccine record. Quickly access full immunization history using the `list_immunizations` tool to verify compliance or check lot numbers.
- When coordinating care, you can immediately review a patient’s entire medical profile by combining `get_patient` details with all their past `list_diagnostics` reports.
- It saves time writing complex queries. Instead of building SQL against the data warehouse, simply ask your agent to pull records using the dedicated tools.

## How It Works

The bottom line is you tell your AI client what data you need, and it handles talking to the Epic API behind the scenes.

1. Subscribe to this MCP and enter your FHIR Server URL, Client ID, and Access Token from your Epic App Orchard registration.
2. Connect your preferred AI client (Claude, Cursor, etc.) to Vinkius and select this connector.
3. Ask your agent a natural language question (e.g., 'List all active medications for patient X') and the system pulls the data.

## Frequently Asked Questions

**How do I find a patient's full history using list_encounters?**
You first use `search_patients` to get the correct ID, then ask the agent to run `list_encounters`. This provides all visits and locations over time, giving you the framework for the entire medical timeline.

**Can I check vaccinations using list_immunizations?**
Yes. The `list_immunizations` tool pulls detailed vaccination records, including the vaccine type, exact administration date, and lot number, which is critical for public health tracking.

**What is the best way to find a patient's current medications?**
Use `list_medications`. This tool provides more than just the drug name; it gives dosage instructions, frequency, and who prescribed it, which is vital for care coordination.

**Does list_observations include blood work details?**
Yes. It handles various observations, including filtering by 'laboratory' to get detailed blood work, vitals signs, and social history data alongside their standard reference ranges.

**When calling get_patient, what credentials do I need to authorize my request?**
You must provide a valid Access Token and Client ID obtained from your Epic App Orchard registration. The MCP handles the FHIR R4 OAuth 2.0 flow, so ensure these tokens are current for successful data retrieval.

**How detailed is the information I get when running list_conditions?**
The results include specific ICD-10 codes, which define the condition. You also receive the clinical status, onset date, and severity level, giving you a full picture of the diagnosis history.

**If I use search_patients and no records are returned, what does that mean for my workflow?**
An empty list means the criteria didn't match any patient in your system. The MCP will return an empty set or a specific error code; you should check spelling or expand your search parameters.

**What clinical details are included when I use list_allergies to check for reactions?**
The tool provides the substance, reaction type, and severity level. It's crucial to review both the reported severity and the current clinical status field for actionable data.

**Can I search for a patient and instantly see their full medical timeline?**
Yes! Use `search_patients` with name or MRN to find the patient, then chain `list_encounters`, `list_conditions`, and `list_medications` to build a full clinical picture. Your agent compiles everything in seconds — no chart-clicking required.

**How do I prepare a patient summary before a care coordination meeting?**
Ask your agent to pull everything at once: 'Show me the full medical history for patient ID abc123.' It will call `get_patient` for demographics, `list_conditions` for active diagnoses, `list_medications` for current prescriptions, and `list_allergies` for safety alerts — delivering a structured briefing ready for your meeting.

**Is this integration read-only? Can it modify patient data?**
This integration is entirely read-only. All 10 tools are query operations — search, list, and retrieve. No tool can create, update, or delete any clinical data. Your Epic FHIR access token controls exactly which patients and resources are visible, enforcing your existing HIPAA access controls.