# MCP Tools Reference

The JondaX MCP server exposes five tools. Assistants call them by name with the parameters below. File uploads take a local file path — the server reads the file and sends it to JondaX for you.

| Tool | Type | Purpose |
|  --- | --- | --- |
| [`upload_pathology_scan`](#upload_pathology_scan) | Async | Upload a lab report / pathology document |
| [`upload_medical_device`](#upload_medical_device) | Sync | Extract readings from a device photo |
| [`get_upload_status`](#get_upload_status) | Query | Check processing & callback status |
| [`list_uploads`](#list_uploads) | Query | List recent uploads to find an `uploadId` |
| [`get_extracted_results`](#get_extracted_results) | Query | Retrieve structured results |


## upload_pathology_scan

Uploads a pathology or lab report (image or PDF) to JondaX for OCR and biomarker extraction. This is **asynchronous**: it returns an `uploadId` immediately, then JondaX processes the document in the background and delivers results to your callback or the portal.

**Parameters**

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `filePath` | string | Yes | Absolute or relative path to the local lab report image or PDF. |
| `isDemo` | boolean | No | Optional flag for demo processing treatment. |


**Example prompt**

> "Upload the lab report at /Users/me/reports/cbc.pdf to JondaX."


**Example response**

```json
{
  "success": true,
  "data": {
    "type": "pathology",
    "status": "uploaded",
    "uploads": [
      {
        "uploadId": "3f2a9c10-...",
        "fileName": "cbc.pdf",
        "message": "File uploaded successfully"
      }
    ],
    "filesCount": 1,
    "message": "1 pathology file(s) uploaded successfully"
  }
}
```

Keep the `uploadId` — you'll use it to check status and retrieve results.

## upload_medical_device

Uploads an image of a medical device reading (pulse oximeter, blood pressure monitor, glucose meter, thermometer, etc.) and extracts the values. This is **synchronous**: the readings come back directly in the response, no callback or polling needed.

**Parameters**

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `filePath` | string | Yes | Absolute or relative path to the local device scan image. |


**Example prompt**

> "Extract the reading from this glucometer photo: /Users/me/photos/glucose.jpg"


**Example response**

```json
{
  "success": true,
  "data": {
    "type": "medical",
    "extractions": [
      {
        "fileName": "glucose.jpg",
        "result": {
          "status": "extracted",
          "success": true,
          "count": 1,
          "items": [
            {
              "index": 0,
              "deviceType": "glucose-meter",
              "data": {
                "glucose": { "value": 5.8, "unit": "mg/dL" },
                "unit": "mmol/L"
              }
            }
          ],
          "message": "Medical data extracted successfully"
        }
      }
    ],
    "filesCount": 1
  }
}
```

## get_upload_status

Checks the current processing status of a pathology upload using its `uploadId`, including whether results have been delivered to your callback. This is a **one-time check** — call it once and report the current state. Processing can take a long time (it may include manual human review), so don't call it repeatedly in a loop to wait for completion; let the user check again later.

**Parameters**

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `uploadId` | string (UUID) | Yes | The UUID returned by `upload_pathology_scan`. |


**Status values**

| Status | Meaning |
|  --- | --- |
| `uploaded` | File received, queued for processing. |
| `processing` | Extraction and transformation in progress. |
| `completed` | Processing finished; results available. |
| `failed` | Processing could not complete. |


**Example prompt**

> "What's the status of upload 3f2a9c10-...?"


## list_uploads

Lists your recent uploads (newest first) with their `uploadId`, file name, status, upload date and expiry date. Use this to **discover an `uploadId`** when you don't already have it — for example "what did I upload recently?" — then follow up with `get_upload_status` or `get_extracted_results`.

**Parameters** (all optional)

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `limit` | number | No | Maximum number of uploads to return (1–100). Defaults to 10. |
| `fromDate` | string | No | Only include uploads on or after this date (inclusive, ISO-8601, e.g. `2026-08-01`). |
| `toDate` | string | No | Only include uploads on or before this date (inclusive). Set `fromDate` == `toDate` for a single day. |
| `status` | string | No | Filter by status: `uploaded`, `processing`, `completed`, or `failed`. |


**Example prompts**

> "List my recent uploads."


> "Show me the last 5 completed uploads."


> "What did I upload between August 1st and 7th?"


**Example response**

```json
{
  "success": true,
  "count": 2,
  "uploads": [
    {
      "uploadId": "3f2a9c10-...",
      "transactionId": 3120,
      "fileName": "cbc.pdf",
      "status": "completed",
      "uploadedDate": "2026-08-27T10:37:13.070Z",
      "expiresAt": "2026-09-26T10:37:13.070Z"
    },
    {
      "uploadId": "a50f3bc1-...",
      "transactionId": 3115,
      "fileName": "lab-report.pdf",
      "status": "processing",
      "uploadedDate": "2026-08-26T14:02:10.123Z",
      "expiresAt": "2026-09-25T14:02:10.123Z"
    }
  ]
}
```

When nothing matches, `count` is `0` and `uploads` is empty. Uploads are retained for **30 days**.

## get_extracted_results

Retrieves the structured extracted results (biomarkers, values, reference ranges) for a completed upload. Defaults to your account's configured output format; you can override the format per call. Results are retained for **30 days** after upload.

**Parameters**

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| `uploadId` | string (UUID) | Yes | The UUID of the processed document. |
| `format` | string | No | Output format override. One of `json`, `fhir_json`, `hl7`, `fhir_xml`, `csv`, `parquet`. Defaults to your account's configured format. |


**Behaviour**

- If processing is complete, returns the structured results in the requested format.
- If processing is still in progress, JondaX returns an **HTTP 202 Accepted** response. Don't retry in a loop — let the user check again later (processing may include manual review).


**Example prompt**

> "Get the results for 3f2a9c10-... as FHIR JSON."


## Typical flow

A pathology run through the assistant usually looks like this:

1. `upload_pathology_scan` → returns an `uploadId`.
2. `get_upload_status` → a **one-time** check of the current state. Processing can take a long time (it may include manual human review), so check once and report the result rather than looping — the user can ask again later.
3. `get_extracted_results` → once the status is `completed`, retrieve the structured output in your chosen format.


> **Note for assistants:** `get_upload_status` and `get_extracted_results` are point-in-time checks, not subscriptions. Don't call them repeatedly in a loop to wait for a result — a run can take a while, especially when manual review is involved. Check once, tell the user the current state, and let them come back later.


Medical device readings are a single synchronous step — `upload_medical_device` returns the values directly.

See the [Setup guide](/docs/mcp/setup) to connect the server, or the [Overview](/docs/mcp/overview) for how MCP fits into JondaX.