Tools reference - PracticeHub API

Clients discover these automatically with tools/list; this page is the human-readable version. There are two kinds:

Generic tools are driven by the API’s resource registry, so they cover every resource on the API Reference — including ones added after this page was written.
Curated tools wrap the common clinical lookups with friendlier parameters. They follow the same rules as the generic tools and the REST API.

The MCP server is read-only during the limited rollout. A connected assistant can look anything up but cannot create, change or delete records — bookings, payments and record edits are made in PracticeHub itself (or through the REST API with an API key). Write tools will be added when the rollout widens.

A typical lookup

Discover

list_entity_types once per session — the agent learns the resources, attributes and filters.

Find the patient

patient-lookup-tool with a name, phone or email; patient-info-tool for the full record.

Find the reference ids

query_entities on locations, appointment_types and practitioners?active=eq:1.

Check availability

check_availability with the location and appointment type (and optionally a practitioner and date range) — the agent reports only slots that are actually free, ready to be booked in PracticeHub.

Generic tools

list_entity_types

Read-only, no parameters — the MCP form of GET /schema. Returns every resource with its attributes (filterable / sortable flags) and the related records a read embeds. It also lists each resource’s write_operations and their input rules: those describe what the REST API accepts, so an agent understands the model — they are not tools this server offers. During the limited rollout the server registers no write tools at all.

query_entities

Read-only. Lists a resource with the API’s filter syntax.

Parameter	Type	Required	Description
`entity`	string	Yes	Resource name, e.g. `patients`, `appointments`
`filters`	string	No	Query-string filters: `last_name=like:%smith%&created_at=gte:2026-01-01`; metadata as `metadata[key]=op:value`
`sort`	string	No	`attr:asc` or `attr1,attr2:desc`
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Rows per page (default 25, max 100)

Returns the same data / meta / links envelope as the REST list endpoint.

get_entity

Read-only. One record by id.

Parameter	Type	Required	Description
`entity`	string	Yes	Resource name
`id`	integer	Yes	Record id

check_availability

Read-only. Free, bookable slots for a location and appointment type — the MCP form of GET /availability. Slots are in the clinic timezone with the practitioner_id, starts_at and ends_at identifying each free slot; unavailable_dates lists days with nothing free.

Parameter	Type	Required	Description
`location_id`	integer	Yes	Location id
`appointment_type_id`	integer	Yes	Appointment type id
`practitioner_id`	integer	No	Limit to one practitioner
`from`	string	No	`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`; default today
`to`	string	No	Default 7 days from `from`; at most 31 days
`visibility`	string	No	`online` (patient view, default) or `all` (staff view)
`max_per_day`	integer	No	Cap on slots per day (1–50)
`rescheduled_appointment_id`	integer	No	When an existing appointment is being moved: its id, so its current time isn’t counted as busy

Curated tools

patient-lookup-tool

Read-only. Searches patients by name, phone number or email.

Parameter	Type	Required	Description
`query`	string	Yes	Name, phone number or email
`limit`	integer	No	Max results (default 10, at most 25)

patient-info-tool

Read-only. Detailed information about one patient.

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient id

appointment-lookup-tool

Read-only. A patient’s appointments — upcoming only by default.

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient id
`upcoming_only`	boolean	No	Only future appointments (default true)

​A typical lookup

​Generic tools

​Curated tools

A typical lookup

Generic tools

Curated tools