### update_records Response (UPDATE_STARTED)

Source: https://docs.healthex.io/api-documentation/mcp-server/mcp-access

Example response for the update_records tool with status UPDATE_STARTED. Indicates a refresh was successfully started.

```json
{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"status\": \"UPDATE_STARTED\",\n  \"message\": \"A background refresh of your health records has been initiated. This typically takes only a few minutes, although some records may take longer (up to an hour) to complete.\"\n}"
      }
    ],
    "structuredContent": {
      "status": "UPDATE_STARTED",
      "message": "A background refresh of your health records has been initiated. This typically takes only a few minutes, although some records may take longer (up to an hour) to complete."
    }
  }
}
```

--------------------------------

### MCP request with access token

Source: https://docs.healthex.io/api-documentation/mcp-server/oauth-flow

Example MCP request using the access token. Include the access token in all MCP requests. This example calls the search tool with a query.

```http
POST /mcp  
  
  
  
  
{  
  "jsonrpc": "2.0",  
  "id": 1,  
  "method": "tools/call",  
  "params": {  
    "name": "search",  
    "arguments": {  
      "query": "diabetes medications"  
    }  
  }  
}  
```

--------------------------------

### JWKS response example

Source: https://docs.healthex.io/api-documentation/federated-login

Example JWKS response from https://api.healthex.io/hosted-sso/jwks. Only public parameters are published; the set may contain multiple keys during rotation, so select by kid and never assume a single entry.

```json
{
  "keys": [
    {
      "kid": "hx-hosted-sso-2026-01",
      "kty": "RSA",
      "use": "sig",
      "alg": "RS384",
      "n": "wJ8f...",
      "e": "AQAB"
    }
  ]
}
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://docs.healthex.io/api-documentation/mcp-server/oauth-flow

Discovers OAuth 2.0 endpoints and supported features for the MCP Server.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
Discovers OAuth 2.0 endpoints and supported features for the MCP Server. This endpoint is optional but recommended to avoid hardcoding URLs.

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server

### Parameters
None

### Response
#### Success Response (200)
- **issuer** (string) - The issuer identifier for the OAuth server.
- **authorization_endpoint** (string) - URL for the authorization endpoint.
- **token_endpoint** (string) - URL for the token endpoint.
- **revocation_endpoint** (string) - URL for the revocation endpoint.
- **registration_endpoint** (string) - URL for the client registration endpoint.
- **scopes_supported** (array of strings) - List of supported OAuth scopes.
- **code_challenge_methods_supported** (array of strings) - List of supported PKCE code challenge methods.

#### Response Example
```json
{
  "issuer": "https://api.healthex.io",
  "authorization_endpoint": "https://api.healthex.io/oauth/authorize",
  "token_endpoint": "https://api.healthex.io/oauth/token",
  "revocation_endpoint": "https://api.healthex.io/oauth/revoke",
  "registration_endpoint": "https://api.healthex.io/oauth/register",
  "scopes_supported": ["patient/*.read", "offline_access"],
  "code_challenge_methods_supported": ["S256"]
}
```
```

--------------------------------

### Add Patients Request Body Example

Source: https://docs.healthex.io/api-documentation/add-patients-to-projects/add-patients-by-api

Example request body for the Add Patients endpoint. It includes four patient records: two with explicit contactPreference, one with only a phone (defaults to phone), and one with both contacts but no preference (defaults to email). Required fields are firstName, lastName, at least one contact method, and languagePreference.

```json
{

    "patients": [

        {

            "firstName": "Sarah",

            "lastName": "Johnson",

            "externalId": "PAT-2024-001",

            "dateOfBirth": "03/15/1985",

            "email": "sarah.johnson@email.com",

            "phone": "5551234567",

            "contactPreference": "email",

            "languagePreference": "en"

        },

        {

            "firstName": "Carlos",

            "lastName": "Rodriguez",

            "email": "carlos.rodriguez@email.com",

            "phone": "5559876543",

            "contactPreference": "phone",

            "languagePreference": "es"

        },

        {

            "firstName": "Maria",

            "lastName": "Garcia",

            "phone": "5551112222",

            "languagePreference": "es"

        },

        {

            "firstName": "David",

            "lastName": "Chen",

            "email": "david.chen@email.com",

            "phone": "5554445555",

            "languagePreference": "en"

        }

    ]

}
```

--------------------------------

### Initialize Request

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

Call this first to establish protocol version and capabilities. The response includes the server's protocol version and capabilities.

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

--------------------------------

### GET consent records with pagination and date filtering

Source: https://docs.healthex.io/api-documentation/consent-auditing/getting-consent-record-details

Retrieves consent records with optional pagination and filtering parameters. The example uses limit=50 and offset=0.

```http
GET https://api.healthex.io/v1/patients/consents?patientId=17d4513f-73e8&limit=50&offset=0
```

--------------------------------

### Example Request for Usage Summary

Source: https://docs.healthex.io/api-documentation/usage

Curl command to fetch usage summary for a date range. Requires a Bearer JWT token.

```bash
curl -X GET "https://api.healthex.io/v1/usage/summary?startDate=2026-08-01T07:00:00Z&endDate=2026-10-01T06:59:59Z" \
  -H "Authorization: Bearer <JWT Token>"  

```

--------------------------------

### initialize

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

The initialize method establishes protocol version and capabilities. It should be called first to initialize the session.

```APIDOC
## MCP Method: initialize

### Description
Establish protocol version and capabilities. Call this first to initialize the session.

### Method
initialize

### Request Body
- **jsonrpc** (string) - Required - Must be "2.0"
- **id** (number | string) - Required - Request identifier
- **method** (string) - Required - Must be "initialize"
- **params** (object) - Required - Parameters
  - **protocolVersion** (string) - Required - Protocol version
  - **capabilities** (object) - Optional - Client capabilities
  - **clientInfo** (object) - Required - Client information
    - **name** (string) - Required - Client name
    - **version** (string) - Required - Client version

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Your Client Name",
      "version": "1.0.0"
    }
  }
}

### Response
#### Success Response (200)
- **jsonrpc** (string) - Protocol version
- **id** (number | string) - Request identifier
- **result** (object) - Result object
  - **protocolVersion** (string) - Protocol version
  - **capabilities** (object) - Server capabilities
  - **serverInfo** (object) - Server information
    - **name** (string) - Server name
    - **version** (string) - Server version
    - **description** (string) - Server description

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "HealthEx MCP Server",
      "version": "1.0.0",
      "description": "MCP server for healthcare data search for patients"
    }
  }
}
```

--------------------------------

### GET patient-flow-progress API call

Source: https://docs.healthex.io/api-documentation/patient-flow-progress

Use this GET request to retrieve the patient flow progress. It requires a patient or API JWT token for authentication, passed as a Bearer token in the Authorization header. The request uses the project ID and patient external ID from the example values.

```http
GET https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/patient-flow-progress?externalId=9832cdf-73e8  

Accept: application/json  

Authorization: Bearer <JWT token>  

```

--------------------------------

### Example Request for Usage Details

Source: https://docs.healthex.io/api-documentation/usage

Curl command to fetch usage details for January 2024 with page=1 and pageSize=20. Requires a Bearer JWT token.

```bash
curl -X GET "https://api.healthex.io/v1/usage/details?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&page=1&pageSize=20" \
  -H "Authorization: Bearer <JWT Token>"  

```

--------------------------------

### Time Range Customization Examples

Source: https://docs.healthex.io/api-documentation/mcp-server/mcp-tools

Shows how to customize the historical data range for clinical history tools using the 'years' parameter. The examples include getting 5 years of lab history, complete immunization history, recent medication changes, and filtering vitals by type.

```javascript
// 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"] })  
```

--------------------------------

### Tools/List Request

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

Lists all available tools. The response includes tool names, descriptions, and input schemas.

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

--------------------------------

### GET /consents/{id} Request

Source: https://docs.healthex.io/api-documentation/consent-auditing/getting-consent-record-details

Retrieves details for a specific consent record by its ID. Requires a valid JWT token. The example fetches consent record ID 21.

```http
GET https://api.healthex.io/v1/consents/21
```

--------------------------------

### Data Requestor Response Example

Source: https://docs.healthex.io/api-documentation/add-patients-to-projects/add-patients-by-api

Example response for a data requestor adding a patient with direct patient data. Shows the `externalId` field instead of `mrn`.

```json
{  

    "successfulPatients": [  

        {  

            "patientIndex": 0,  

            "email": "datarequestor.patient@email.com",  

            "phone": "+15551234567",  

            "externalId": "EXT-PAT-001",  

            "referenceId": "hx_abc123def456"  

        }  

    ]  

}  



```

--------------------------------

### Example Response for Usage Summary

Source: https://docs.healthex.io/api-documentation/usage

JSON response containing total TEFCA and non-TEFCA query counts, total queries, and monthly usage breakdown with active users and queries by source.

```json
{  
    "tefcaQueries": 150,  
    "nonTefcaQueries": 75,  
    "totalQueries": 225,  
    "monthlyUsage": [  
        {  
            "month": "2026-08",  
            "activeUsers": 92,  
            "tefcaQueries": 100,  
            "nonTefcaQueries": 40,  
            "totalQueries": 140,  
            "queriesBySource": [  
                { "source": "TEFCA", "queries": 100 },  
                { "source": "FASTEN", "queries": 10 },  
                { "source": "PARTICLE", "queries": 8 },  
                { "source": "HEALTHEX_EPIC", "queries": 7 },  
                { "source": "HEALTHEX_ORACLE", "queries": 6 },  
                { "source": "HEALTHEX_ECW", "queries": 5 },  
                { "source": "HEALTHEX_ATHENA", "queries": 4 }  
            ]  
        },  
        {  
            "month": "2026-09",  
            "activeUsers": 79,  
            "tefcaQueries": 50,  
            "nonTefcaQueries": 35,  
            "totalQueries": 85,  
            "queriesBySource": [  
                { "source": "TEFCA", "queries": 50 },  
                { "source": "FASTEN", "queries": 9 },  
                { "source": "PARTICLE", "queries": 8 },  
                { "source": "HEALTHEX_EPIC", "queries": 6 },  
                { "source": "HEALTHEX_ORACLE", "queries": 5 },  
                { "source": "HEALTHEX_ECW", "queries": 4 },  
                { "source": "HEALTHEX_ATHENA", "queries": 3 }  
            ]  
        }  
    ]  
}  

```

--------------------------------

### GET getPatientConsentStatus

Source: https://docs.healthex.io/api/get-patient-consent-status

Retrieves the consent status for a patient. Provide a patientId as a path parameter and optionally a projectId as a query parameter to get project-specific consent status.

```APIDOC
## GET getPatientConsentStatus

### Description
Get the consent status for a patient. If projectId is provided, returns the project consent status. Otherwise, returns the IAS (Individual Access Services) consent status.

### Method
GET

### Endpoint
getPatientConsentStatus

### Parameters
#### Path Parameters
- **patientId** (string) - Required - Patient ID

#### Query Parameters
- **projectId** (string) - Optional - Project ID to check project-specific consent status

### Response
#### Success Response (200)
The consent status of the patient

```

--------------------------------

### initialize

Source: https://docs.healthex.io/api-documentation/mcp-server/mcp-access

Initializes the MCP session. Optional for test patients.

```APIDOC
## [MCP] initialize

### Description
Initializes the MCP session. Optional for test patients.

### Method
MCP method call (JSON-RPC 2.0)

### Endpoint
`initialize`

### Parameters
#### Params
- `protocolVersion` (string) - Required - Protocol version to use.
- `capabilities` (object) - Required - Client capabilities.
- `clientInfo` (object) - Required - Client information with `name` and `version`.

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

### Response
No response example provided in the source.
```

--------------------------------

### Initialize Response

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

Response to the initialize request, confirming protocol version and server capabilities.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "HealthEx MCP Server",
      "version": "1.0.0",
      "description": "MCP server for healthcare data search for patients"
    }
  }
}
```

--------------------------------

### GET /FHIR/R4/Person

Source: https://docs.healthex.io/api-documentation/fhir-server

This snippet documents the GET /FHIR/R4/Person endpoint used to resolve a patient ID by searching the Person resource with either an external ID or a reference ID.

```APIDOC
## [GET] /FHIR/R4/Person

### Description
Searches for a Person resource to resolve a patient ID using either an external ID or a reference ID. This is required before using other HealthEx FHIR APIs.

### Method
GET

### Endpoint
https://api.healthex.io/FHIR/R4/Person

### Parameters
#### Query Parameters
- **externalId** (string) - Required (if searching by external ID) - The external ID of the patient.
- **referenceId** (string) - Required (if searching by reference ID) - The reference ID of the patient.
- **projectId** (string) - Required - The project ID associated with the identifier.

### Request Example
GET https://api.healthex.io/FHIR/R4/Person?externalId=EXT-1234&projectId=eaa98f2a-34ae

### Response
#### Success Response (200)
- **resourceType** (string) - Always "Bundle".
- **type** (string) - Always "searchset".
- **total** (integer) - Number of results (0 or 1).
- **link** (array) - Contains a self link.
- **entry** (array) - Contains the matched Person resource if found.

#### Response Example
{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthex.io/FHIR/R4/Person?externalId=EXT-1234&projectId=eaa98f2a-34ae"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80",
            "search": {
                "mode": "match"
            },
            "resource": {
                "resourceType": "Person",
                "id": "19cff418-7d80",
                "name": [
                    {
                        "family": "Patient",
                        "given": ["Example"],
                        "use": "usual"
                    }
                ],
                "birthDate": "1990-01-01",
                "gender": "male",
                "link": [
                    {
                        "target": {
                            "reference": "Patient/19cff418-7d80"
                        },
                        "assurance": "level4"
                    },
                    {
                        "target": {
                            "reference": "Patient/72bd3ff3-0df0"
                        },
                        "assurance": "level4"
                    }
                ]
            }
        }
    ]
}
```

--------------------------------

### Healthcare Organization (MRN) Response Example

Source: https://docs.healthex.io/api-documentation/add-patients-to-projects/add-patients-by-api

Example response for a healthcare organization adding a patient using MRN-based additions. The `mrn` field contains the Medical Record Number.

```json
{  

    "successfulPatients": [  

        {  

            "patientIndex": 0,  

            "email": "patient@hospital.com",  

            "phone": "+15559876543",  

            "mrn": "MRN123456",  

            "referenceId": "hx_def789ghi012"  

        }  

    ]  

}  



```

--------------------------------

### List Available Tools with cURL

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

Lists available tools on the MCP server. Requires an access token. The response will contain the list of tools that can be called.

```bash
curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

--------------------------------

### Example Response for Usage Details

Source: https://docs.healthex.io/api-documentation/usage

JSON response containing total record count, current page, page size, and an array of results with patientId, referenceIds, and query counts.

```json
{  
    "total": 45,  
    "page": 1,  
    "pageSize": 20,  
    "results": [  
        {  
            "patientId": "patient-uuid-1",  
            "referenceIds": ["reference-id-1", "reference-id-2"],  
            "tefcaQueries": 3,  
            "nonTefcaQueries": 2  
        },  
        {  
            "patientId": "patient-uuid-2",  
            "referenceIds": [],  
            "tefcaQueries": 1,  
            "nonTefcaQueries": 0  
        }  
    ]  
}  

```

--------------------------------

### FHIR bundle response example

Source: https://docs.healthex.io/api-documentation/fhir-server

Example response body from the $everything API call. It is a FHIR bundle containing a Person resource and an Observation resource, with links and search metadata.

```json
{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 2,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=0"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80",
            "search": {
                "mode": "match"
            },
            "resource": {
                "resourceType": "Person",
                "id": "19cff418-7d80",
                "name": [
                    {
                        "family": "Lin",
                        "given": ["Derrick"],
                        "use": "usual"
                    }
                ],
                "birthDate": "1973-06-03T00:00:00.000Z",
                "link": [
                    {
                        "target": {
                            "reference": "Patient/eq081-VQEgP8drUUqCWzHfw3",
                            "assurance": "level4"
                        }
                    }
                ]
            }
        },
        {
            "fullUrl": "https://api.healthex.io/FHIR/R4/Observation/00210fd0-9625-486b-a4fd-43f832798c75",
            "search": {
                "mode": "match"
            },
            "resource": {
                "resourceType": "Observation",
                "id": "fqzY4YiPBHqsNx9iRD99etRNX.LClJFf33HYpZC1E1R04",
                "status": "final",
                "category": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                "code": "vital-signs",
                                "display": "Vital Signs"
                            }
                        ],
                        "text": "Vital Signs"
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "system": "http://loinc.org",
                            "code": "55284-4",
                            "display": "Blood pressure systolic and diastolic"
                        }
                    ],
                    "text": "Blood Pressure"
                },
                "subject": {
                    "reference": "Patient/eq081-VQEgP8drUUqCWzHfw3",
                    "display": "Lin, Derrick"
                },
                "encounter": {
                    "reference": "Encounter/e6kBx6PwnxIv.5kCifScsWg3",
                    "identifier": {
                        "use": "usual",
                        "system": "urn:oid:1.2.840.114350.1.13.0.1.7.3.698084.8",
                        "value": "27556"
                    }
                }
            }
        }
    ]
}
```

--------------------------------

### Example FHIR Bundle Response

Source: https://docs.healthex.io/api-documentation/fhir-server

Example response from a Person search. The bundle contains a single Person resource in the entry list; the resource.id is the patient ID needed for subsequent API calls.

```json
{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthex.io/FHIR/R4/Person?externalId=EXT-1234&projectId=eaa98f2a-34ae"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80",
            "search": {
                "mode": "match"
            },
            "resource": {
                "resourceType": "Person",
                "id": "19cff418-7d80",
                "name": [
                    {
                        "family": "Patient",
                        "given": ["Example"],
                        "use": "usual"
                    }
                ],
                "birthDate": "1990-01-01",
                "gender": "male",
                "link": [
                    {
                        "target": {
                            "reference": "Patient/19cff418-7d80"
                        },
                        "assurance": "level4"
                    },
                    {
                        "target": {
                            "reference": "Patient/72bd3ff3-0df0"
                        },
                        "assurance": "level4"
                    }
                ]
            }
        }
    ]
}
```

--------------------------------

### Resources/List Request

Source: https://docs.healthex.io/api-documentation/mcp-server/api-reference

Lists available resources.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/list",
  "params": {}
}
```

--------------------------------

### Example Request Body for Adding Patients

Source: https://docs.healthex.io/api-documentation/add-patients-to-projects/add-patients-by-api

Example request body for adding patients to a project. Each MRN can optionally include a patientNotificationType; if omitted, the default is ENROLLMENT_REQUEST. The system automatically retrieves patient details from the EHR.

```json
{

    "mrns": [

        {

            "mrn": "MRN123456",

            "patientNotificationType": "PRESCREENING_REQUEST"

        },

        {

            "mrn": "MRN789012",

            "patientNotificationType": "ENROLLMENT_REQUEST"

        },

        {

            "mrn": "MRN345678",

            "patientNotificationType": "INFORMATION_SENT"

        },

        {

            "mrn": "MRN999888"

        }

    ]

}
```

--------------------------------

### Integration Flow Steps

Source: https://docs.healthex.io/api-documentation/mcp-server

Shows the sequential steps for integrating with the HealthEx MCP Server, from registering an OAuth client to calling MCP endpoints with a Bearer token.

```text
1. Register OAuth Client  

   ↓  

2. Implement OAuth 2.0 + PKCE  

   ↓  

3. User grants consent (redirects to HealthEx)  

   ↓  

4. User selects healthcare organizations to share data from  

   ↓  

5. Receive authorization code  

   ↓  

6. Exchange code for access token  

   ↓  

7. Call MCP endpoints with Bearer token  

```