MCP reference / Analytics

Analytics and search tools

Six tools covering headline figures, three bucketed reports, the audit trail and cross-entity search. The reports and the audit log are owner-only.

How to read this

Each tool below lists its arguments exactly as the input schema declares them: the type, whether it is required, the permitted values where the schema fixes them, and what the schema says the argument means. None of it is written here. An amount in cents, a default that applies when a field is left out, which action needs which id: those sentences come from the tool itself.

practiceId is never an argument. It comes from your token, and the write paths strip it if a client sends one anyway.

A tool that writes shows one example per action, because what an action needs is not what the input schema marks required: the schema requires action and leaves the rest to the action. Every example is a complete tools/call request whose arguments are checked, when this page is built, against the same object the handler parses. Errors come back inside a 200 response with isError set: the MCP overview has that envelope, and the full catalogue lists every tool at a glance.

Analytics and search

Aggregates and cross-entity search. The three reports and the audit log are owner-only.

get_dashboard_kpis

Read-onlyAny member

Headline figures — today's appointments, outstanding balances, recent activity counts.

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

get_appointments_report

Read-onlyOwner only

Appointment counts bucketed over a date range. groupBy is day, week or month.

Arguments

Tool	Type	Required?	What it means
from	string	Required	Start of the range, inclusive. YYYY-MM-DD.
to	string	Required	End of the range, inclusive. YYYY-MM-DD. Must be after from.
groupBy	string: day \| week \| month	Optional	Bucket size for the series. Defaults to day.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_appointments_report",
    "arguments": {
      "from": "2026-11-02",
      "to": "2026-11-02"
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
forbidden	403	The caller is not an owner of the practice.
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

get_revenue_report

Read-onlyOwner only

Revenue totals bucketed over a date range. groupBy is day, week or month.

Arguments

Tool	Type	Required?	What it means
from	string	Required	Start of the range, inclusive. YYYY-MM-DD.
to	string	Required	End of the range, inclusive. YYYY-MM-DD. Must be after from.
groupBy	string: day \| week \| month	Optional	Bucket size for the series. Defaults to day.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_revenue_report",
    "arguments": {
      "from": "2026-11-02",
      "to": "2026-11-02"
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
forbidden	403	The caller is not an owner of the practice.
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

get_patient_acquisition_report

Read-onlyOwner only

New-patient counts bucketed over a date range. groupBy is day, week or month.

Arguments

Tool	Type	Required?	What it means
from	string	Required	Start of the range, inclusive. YYYY-MM-DD.
to	string	Required	End of the range, inclusive. YYYY-MM-DD. Must be after from.
groupBy	string: day \| week \| month	Optional	Bucket size for the series. Defaults to day.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_patient_acquisition_report",
    "arguments": {
      "from": "2026-11-02",
      "to": "2026-11-02"
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
forbidden	403	The caller is not an owner of the practice.
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

list_audit_log

Read-onlyOwner only

Read the practice audit trail, newest first. Filter by entity type and a date range.

Arguments

Tool	Type	Required?	What it means
type	string	Optional	Action type to filter by, e.g. "INSERT_BILLING_ENTRY". Omit for all types.
from	string	Optional	Only entries on or after this date. YYYY-MM-DD.
to	string	Optional	Only entries on or before this date. YYYY-MM-DD.
limit	integer	Optional	How many entries to return. Asked what happened in a period, use the maximum: a day of a busy practice runs to dozens of entries, and there is no reason to summarise from the newest twenty. Defaults to 50; at most 200 (a larger value is lowered to it, not rejected).
offset	integer	Optional	How many entries to skip, for paging back through the trail. At most 100000.

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
forbidden	403	The caller is not an owner of the practice.
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

search

Read-onlyAny member

Cross-entity search over the practice — patients, appointments and more.

Arguments

Tool	Type	Required?	What it means
q	string	Required	The text to search for.
limit	integer	Optional	Maximum results per group. Defaults to 10; at most 50 (a larger value is lowered to it, not rejected).

Example call

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

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "...": "the requested records" },
    "content": [{ "type": "text", "text": "<the same JSON>" }]
  }
}

Errors

Code	Status	When
validation_failed	400	An argument is missing, of the wrong type, or outside its allowed values.
plan_feature_required	403	The practice's plan does not include this. MCP needs Complete.

Common questions

Patient records are encrypted, both where they are stored and on their way to your screen. Files are private, and a link to one stops working after a short time. Changes to patient records are recorded, with who made them and when. There is no shared practice password: everyone has their own account. On the Complete plan, the practice owner can also require two-step sign-in for the whole team.

Yes. The practice owner can export the patient list, the reports and the activity log to a spreadsheet file (CSV) from the app, and anyone in the practice can download its files at any time. Your practice data belongs to you, and there is no export fee or waiting period. That holds on either plan, during the trial, and after you cancel.

HyperCRM is paid software. Every practice starts with a 30-day free trial of the Complete plan, with no card needed. After that, Essential starts at €19 a month and Complete at €34, VAT included. The price depends on how many practitioners you have. Every price is on the pricing page, so you never need a sales call.