MCP Access for Test Patients

Test patients can access the MCP (Model Context Protocol) endpoint directly without going through the OAuth flow or consent verification. This enables rapid testing and development of AI integrations.

General Test Patients Guide

For general information about creating and managing test patients, see the Test Patients documentation.

Quick Start

1. Generate Admin Token

Generate an admin token using your API Key and Secret:

curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "{your_api_key}",
    "apiSecret": "{your_api_secret}"
  }'

Response:

{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": 1738368725
}

API Credentials

You can create your API Key and Secret in the admin Healthex dashboard.

2. Create a Test Patient

curl -X POST "https://api.healthex.io/v1/organizations/{orgId}/test-patients" \
  -H "Authorization: Bearer {admin_token}"

Response:

{
  "patient": {
    "id": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75",
    "email": "test-patient+dqKVeMid8N41@example.com",
    "firstName": "Test",
    "lastName": "Patient",
    "isTestPatient": true
  },
  "password": "zkWZTH$$BmfTAOW4"
}

3. Add Test Patient to Project

Add the test patient to a project using a researcher or org admin token:

curl -X POST "https://api.healthex.io/v1/projects/{projectId}/patients" \
  -H "Authorization: Bearer {researcher_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "patients": [
      {
        "email": "test-patient+dqKVeMid8N41@example.com",
        "firstName": "Test",
        "lastName": "Patient",
        "languagePreference": "en"
      }
    ],
    "suppressNotifications": true
  }'

Response:

{
    "totalProcessed": 1,
    "successCount": 1,
    "errorCount": 0,
    "duplicatesCount": 0,
    "errors": [],
    "duplicates": [],
    "successfulPatients": [
        {
            "patientIndex": 0,
            "email": "test-patient+SavtDTm3meXJ@sampleresearch.com",
            "referenceId": "626133e4-738b-41a3-bf26-651fa94d45f3"
        }
    ]
}

suppressNotifications

Set suppressNotifications: true to prevent sending invitation emails to test patients.

4. Generate Patient Token

curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test-patient+dqKVeMid8N41@example.com",
    "password": "zkWZTH$$BmfTAOW4",
    "projectId": "658ac9e4-2a8b-4775-a58f-06ef6d65d914"
  }'

Response:

{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": 1738368725,
  "user": {
    "type": "PATIENT",
    "id": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75",
    "firstName": "Test",
    "lastName": "Patient",
    "isTestPatient": true
  }
}

Project ID

The projectId is used by the MCP endpoint for AI agent tracking, analytics, and to match patient consent against the project.

Update consent for the test patient against the project using the patient token:

curl -X POST "https://api.healthex.io/v1/projects/{projectId}/test-patients/{patientId}/consent" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "consentStatus": "OPTED_IN"
  }'

Response:

{
  "consentRecordId": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75"
}

Project ID Match

The projectId in the URL must match the project ID associated with the patient token.

6. Upload Documents

Use the patient token to upload a zip file containing documents:

curl -X POST "https://api.healthex.io/v1/patients/{patientId}/upload-documents" \
  -H "Authorization: Bearer {patient_token}" \
  -F "file=@documents.zip"

Response:

{
  "batchId": "1addc6fa-3c59-4915-b0ba-ae2a31ff1f75"
}

Patient Authentication Required

This endpoint requires authentication as the patient (using the token from step 4). The patientId in the URL must match the authenticated patient.

7. Call MCP Endpoint

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_health_summary",
      "arguments": {}
    }
  }'

MCP Endpoint Reference

Endpoint

POST /mcp

Headers

Header	Value	Required
Authorization	Bearer {patient_token}	Yes
Content-Type	application/json	Yes

No Accept Header Needed

For test patients, the Accept header is automatically set. Regular MCP clients need Accept: application/json, text/event-stream.

Request Body

JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {}
  }
}

Available Tools

get_health_summary

Get a comprehensive health overview including conditions, medications, allergies, and recent vitals.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_health_summary",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Health Summary for John Doe\n\n## Active Conditions\n- Type 2 Diabetes Mellitus (diagnosed 2020-03-15)\n- Essential Hypertension (diagnosed 2019-08-22)\n\n## Current Medications\n- Metformin 500mg twice daily\n- Lisinopril 10mg once daily\n\n## Allergies\n- Penicillin (severe - anaphylaxis)\n\n## Recent Vitals (2024-01-15)\n- Blood Pressure: 128/82 mmHg\n- Heart Rate: 72 bpm\n- Weight: 185 lbs"
      }
    ]
  }
}

search

Semantic search across all health records.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "diabetes medications"
    }
  }
}

Parameter	Type	Required	Description
query	string	Yes	Search query

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Search Results for \"diabetes medications\"\n\n## Medication Records\n1. **Metformin 500mg** - Started 2020-03-20\n   - Twice daily with meals\n   - For Type 2 Diabetes management\n\n2. **Glipizide 5mg** - Started 2021-06-15, Ended 2022-01-10\n   - Once daily before breakfast\n   - Discontinued due to hypoglycemia\n\n## Clinical Notes\n- 2024-01-15: HbA1c improved to 6.8%, continue current diabetes regimen"
      }
    ]
  }
}

get_conditions

Get medical conditions history.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_conditions",
    "arguments": {
      "years": 3,
      "beforeDate": "2024-01-01"
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Medical Conditions\n\n## Active Conditions\n| Condition | Onset Date | Status |\n|-----------|------------|--------|\n| Type 2 Diabetes Mellitus | 2020-03-15 | Active |\n| Essential Hypertension | 2019-08-22 | Active |\n| Hyperlipidemia | 2021-02-10 | Active |\n\n## Resolved Conditions\n| Condition | Onset Date | Resolved Date |\n|-----------|------------|---------------|\n| Acute Bronchitis | 2023-01-05 | 2023-01-20 |\n| Ankle Sprain | 2022-06-15 | 2022-08-01 |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2021-01-01 to 2024-01-01\" }_"
      }
    ]
  }
}

get_medications

Get medication history with dosing details.

Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_medications",
    "arguments": {
      "years": 3
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Medications\n\n## Current Medications\n| Medication | Dosage | Frequency | Start Date | Prescriber |\n|------------|--------|-----------|------------|------------|\n| Metformin | 500mg | Twice daily | 2020-03-20 | Dr. Smith |\n| Lisinopril | 10mg | Once daily | 2019-09-01 | Dr. Smith |\n| Atorvastatin | 20mg | Once daily at bedtime | 2021-02-15 | Dr. Johnson |\n\n## Past Medications\n| Medication | Dosage | Start Date | End Date | Reason Stopped |\n|------------|--------|------------|----------|----------------|\n| Glipizide | 5mg | 2021-06-15 | 2022-01-10 | Hypoglycemia |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2021-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_labs

Get laboratory test results.

Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_labs",
    "arguments": {
      "years": 3
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Laboratory Results\n\n## Recent Labs (2024-01-15)\n| Test | Result | Reference Range | Status |\n|------|--------|-----------------|--------|\n| HbA1c | 6.8% | 4.0-5.6% | High |\n| Fasting Glucose | 118 mg/dL | 70-100 mg/dL | High |\n| Total Cholesterol | 185 mg/dL | <200 mg/dL | Normal |\n| LDL Cholesterol | 98 mg/dL | <100 mg/dL | Normal |\n| HDL Cholesterol | 52 mg/dL | >40 mg/dL | Normal |\n| Creatinine | 0.9 mg/dL | 0.7-1.3 mg/dL | Normal |\n\n## Previous Labs (2023-07-20)\n| Test | Result | Reference Range | Status |\n|------|--------|-----------------|--------|\n| HbA1c | 7.2% | 4.0-5.6% | High |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2021-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_vitals

Get vital signs (blood pressure, weight, etc.).

Request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_vitals",
    "arguments": {
      "years": 3,
      "vitals": ["Blood Pressure", "Weight"]
    }
  }
}

Parameter	Type	Description
years	number	Years of history (default: 3)
beforeDate	string	End date for pagination (YYYY-MM-DD)
vitals	array	Filter by vital types

Vital types: Blood Pressure, Heart Rate, Body Temperature, Respiratory Rate, Oxygen Saturation, Weight, Height, Body Mass Index

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Vital Signs\n\n## Blood Pressure\n| Date | Systolic | Diastolic | Status |\n|------|----------|-----------|--------|\n| 2024-01-15 | 128 mmHg | 82 mmHg | Normal |\n| 2023-10-20 | 135 mmHg | 88 mmHg | Elevated |\n| 2023-07-12 | 142 mmHg | 92 mmHg | High |\n\n## Weight\n| Date | Weight | BMI |\n|------|--------|-----|\n| 2024-01-15 | 185 lbs | 27.4 |\n| 2023-10-20 | 188 lbs | 27.8 |\n| 2023-07-12 | 192 lbs | 28.4 |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2021-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_allergies

Get allergy and intolerance records.

Request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_allergies",
    "arguments": {
      "years": 5
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Allergies & Intolerances\n\n| Allergen | Type | Severity | Reaction | Recorded Date |\n|----------|------|----------|----------|---------------|\n| Penicillin | Medication | Severe | Anaphylaxis | 2018-05-20 |\n| Sulfa drugs | Medication | Moderate | Rash, hives | 2019-03-15 |\n| Shellfish | Food | Mild | Gastrointestinal upset | 2020-08-10 |\n| Latex | Environmental | Moderate | Contact dermatitis | 2017-11-22 |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2019-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_procedures

Get medical procedures and surgeries.

Request:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_procedures",
    "arguments": {
      "years": 5
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Procedures & Surgeries\n\n| Procedure | Date | Provider | Facility | Notes |\n|-----------|------|----------|----------|-------|\n| Colonoscopy | 2023-06-15 | Dr. Wilson | City Hospital | Screening, no polyps found |\n| Echocardiogram | 2022-11-08 | Dr. Chen | Heart Center | Normal ejection fraction |\n| MRI - Lumbar Spine | 2022-03-22 | Dr. Roberts | Imaging Center | Mild disc bulge L4-L5 |\n| Appendectomy | 2021-08-05 | Dr. Martinez | City Hospital | Laparoscopic, uncomplicated |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2019-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_immunizations

Get vaccination records.

Request:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "get_immunizations",
    "arguments": {
      "years": 10
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Immunization Records\n\n| Vaccine | Date | Dose | Lot Number | Site |\n|---------|------|------|------------|------|\n| Influenza (Flu) | 2023-10-15 | Annual | FL2023-456 | Left arm |\n| COVID-19 (Pfizer) | 2023-09-20 | Booster #2 | EK9788 | Right arm |\n| Tdap | 2022-05-10 | Booster | TD2022-123 | Left arm |\n| Shingrix | 2021-03-15 | Dose 2 of 2 | SH789012 | Left arm |\n| Shingrix | 2021-01-10 | Dose 1 of 2 | SH789011 | Left arm |\n| Pneumococcal (PPSV23) | 2020-11-05 | Initial | PN456789 | Right arm |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2014-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

get_visits

Get clinical visit history.

Request:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_visits",
    "arguments": {
      "years": 3
    }
  }
}

Parameter	Type	Required	Description
years	number		Years of history (default: 3)
beforeDate	string		End date for pagination (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Clinical Visits\n\n| Date | Type | Provider | Facility | Reason |\n|------|------|----------|----------|--------|\n| 2024-01-15 | Office Visit | Dr. Smith | Primary Care Clinic | Diabetes follow-up |\n| 2023-10-20 | Office Visit | Dr. Smith | Primary Care Clinic | Annual physical exam |\n| 2023-08-05 | Urgent Care | Dr. Lee | Urgent Care Center | Upper respiratory infection |\n| 2023-06-15 | Specialist | Dr. Wilson | GI Associates | Colonoscopy screening |\n| 2023-03-10 | Office Visit | Dr. Smith | Primary Care Clinic | Medication review |\n\n---\n_Metadata: { \"hasMoreData\": false, \"dateRange\": \"2021-02-04 to 2024-02-04\" }_"
      }
    ]
  }
}

search_clinical_notes

Search through clinical notes and documentation.

Request:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "search_clinical_notes",
    "arguments": {
      "query": "chest pain",
      "years": 3
    }
  }
}

Parameter	Type	Required	Description
query	string	Yes	Search keyword or phrase
years	number		Years of history (default: 3)
beforeDate	string		End date for search (YYYY-MM-DD)

Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Clinical Notes Search: \"chest pain\"\n\n## Visit Note - 2023-08-05 (Urgent Care)\n**Provider:** Dr. Lee\n\n**Chief Complaint:** Patient presents with chest pain that started this morning.\n\n**History of Present Illness:** 52-year-old male with history of HTN and diabetes presents with substernal chest pain. Pain is described as pressure-like, non-radiating, 4/10 intensity. No shortness of breath, diaphoresis, or nausea. Pain not related to exertion.\n\n**Assessment:** Atypical chest pain, likely musculoskeletal. Low suspicion for ACS given presentation.\n\n**Plan:** EKG normal, troponin negative x2. Discharged with follow-up to PCP in 1 week.\n\n---\n_Found 1 matching note(s)_"
      }
    ]
  }
}

update_and_check_recent_records

Check when records were last updated and get update link.

Request:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "update_and_check_recent_records",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Health Records Status\n\n## Last Updated\nYour health records were last synchronized on **January 15, 2024 at 2:30 PM**.\n\n## Connected Sources\n- City Hospital - Last sync: Jan 15, 2024\n- Primary Care Clinic - Last sync: Jan 15, 2024\n- Quest Diagnostics - Last sync: Jan 10, 2024\n\n## Update Your Records\nTo pull the latest records from your healthcare providers, visit:\nhttps://app.healthex.io/records/update\n\n_Note: Updates may take a few minutes to process._"
      }
    ]
  }
}

Other MCP Methods

Initialize

Initialize the MCP session (optional for test patients).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Test Client",
      "version": "1.0.0"
    }
  }
}

List Tools

Get all available tools.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Error Responses

HTTP Errors

Status	Description
401	Unauthorized - invalid or missing token
403	Forbidden - patient ID mismatch

JSON-RPC Errors

Code	Meaning
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000	Server error (e.g., patient context not found)

Complete Test Flow Example

# 1. Generate admin token using API Key/Secret
curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "{your_api_key}", "apiSecret": "{your_api_secret}"}'

# 2. Create test patient (as org admin)
curl -X POST "https://api.healthex.io/v1/organizations/{orgId}/test-patients" \
  -H "Authorization: Bearer {admin_token}"

# 3. Add test patient to project (as researcher/admin)
curl -X POST "https://api.healthex.io/v1/projects/{projectId}/patients" \
  -H "Authorization: Bearer {researcher_token}" \
  -H "Content-Type: application/json" \
  -d '{"patients": [{"email": "test-patient+xxx@example.com", "firstName": "Test", "lastName": "Patient", "languagePreference": "en"}], "suppressNotifications": true}'

# 4. Get patient token with projectId
curl -X POST "https://api.healthex.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"email": "test-patient+xxx@example.com", "password": "generated_password", "projectId": "{projectId}"}'

# 5. Update consent (as patient)
curl -X POST "https://api.healthex.io/v1/projects/{projectId}/test-patients/{patientId}/consent" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{"consentStatus": "OPTED_IN"}'

# 6. Upload test documents (as patient)
curl -X POST "https://api.healthex.io/v1/patients/{patientId}/upload-documents" \
  -H "Authorization: Bearer {patient_token}" \
  -F "file=@documents.zip"

# 7. Call MCP tools
curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {patient_token}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_health_summary","arguments":{}}}'

Quick Start​

1. Generate Admin Token​

2. Create a Test Patient​

3. Add Test Patient to Project​

4. Generate Patient Token​

5. Update Consent​

6. Upload Documents​

7. Call MCP Endpoint​

MCP Endpoint Reference​

Endpoint​

Headers​

Request Body​

Available Tools​

get_health_summary​

search​

get_conditions​

get_medications​

get_labs​

get_vitals​

get_allergies​

get_procedures​

get_immunizations​

get_visits​

search_clinical_notes​

update_and_check_recent_records​

Other MCP Methods​

Initialize​

List Tools​

Error Responses​

HTTP Errors​

JSON-RPC Errors​

Complete Test Flow Example​

Quick Start

1. Generate Admin Token

2. Create a Test Patient

3. Add Test Patient to Project

4. Generate Patient Token

5. Update Consent

6. Upload Documents

7. Call MCP Endpoint

MCP Endpoint Reference

Endpoint

Headers

Request Body

Available Tools

get_health_summary

search

get_conditions

get_medications

get_labs

get_vitals

get_allergies

get_procedures

get_immunizations

get_visits

search_clinical_notes

update_and_check_recent_records

Other MCP Methods

Initialize

List Tools

Error Responses

HTTP Errors

JSON-RPC Errors

Complete Test Flow Example