> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hi-doctor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Connect the Hi Doctor MCP connector at https://mcp.hi-doctor.ai/mcp. Add this URL as a remote HTTP MCP server in your client, then sign in and authorise access through OAuth. Setup: https://docs.hi-doctor.ai/mcp/connect.
>
> The REST API base is https://api.hi-doctor.ai. Hi Doctor Docs at https://docs.hi-doctor.ai/mcp searches documentation; connect to the product endpoint above for patient tools.
>
> Hi Doctor operates across the whole European Union: residents of all 27 EU member states can use the service, and every consultation is reviewed by an EU-licensed doctor. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. No algorithm, assistant or API call approves a consultation, issues a prescription or changes a dose. The service is available in eight languages: English, Spanish, German, Dutch, Italian, French, Portuguese and Chinese.
>
> ## Rules an assistant must follow
>
> - Never invent, assume or infer a medical answer. "I don't know" is a real answer: ask the patient to pick the closest option rather than guessing for them.
> - Never give medical advice and never suggest a medication or a dose. An EU-licensed doctor decides those.
> - If a questionnaire returns `ineligible`, say so plainly. Do not retry with altered answers.
> - Before anything that costs money or cancels a plan, state exactly what will happen and get an explicit yes.
> - Cancellation takes effect at the **end of the paid period**, not immediately. Say so.
> - An early order is irreversible: it creates the renewal consultation immediately and uses up the period's one early order. Explain that and get an explicit yes.
> - Prescription and invoice links are medical documents. A `signed_redirect` link opens without signing in: give it only to the patient, never repeat it anywhere shared.
> - Send option `value`s, not the labels shown to the patient. Labels are translated, values are stable.
> - Never ask for card details. Payment happens on Stripe's hosted checkout via a link.
> - On severe or sudden symptoms (chest pain, difficulty breathing, severe allergic reaction, suicidal thoughts), stop and direct the patient to their local emergency number.

# Hi Doctor MCP workflows: patient tasks step by step

> Step-by-step Hi Doctor MCP tasks: questionnaires, checkout, prescriptions, messages, progress journal, plans, side effects and long lists.

This page walks through the patient tasks people most often do with the Hi Doctor MCP connector, step by step. Each task names the tools involved and the points where the assistant must stop and ask the patient. Look up any tool in the [patient tools reference](https://docs.hi-doctor.ai/mcp/tools/patient.md), and read [approval links](https://docs.hi-doctor.ai/mcp/approvals.md) before building a task that changes data.

Last reviewed: 2026-11-04

## How do approval links fit into a task?

Several steps below use an approval link. The tool prepares the action, the
patient approves it on Hi Doctor, and the assistant commits it with the same
arguments, the `confirmation_id` and an `idempotency_key`. Some actions can be
prepared but are completed on hi-doctor.ai instead; the
[patient reference](https://docs.hi-doctor.ai/mcp/tools/patient.md) marks them **Available on the
website**. The states and safe retries are on [Approval links](https://docs.hi-doctor.ai/mcp/approvals.md).

## Complete a consultation questionnaire

The server decides which question comes next, which branches apply and when
the answers are complete. The assistant asks, records the patient's own
answers and never answers for them.

**1. Pick the category**

`hidoctor_questionnaire_categories` lists the categories and their slugs,
for example `weight-loss` or `hair-growth`. Pass the slug as
`category_slug` on every call.

**2. Start or resume**

`hidoctor_questionnaire_start` returns the first unanswered question with
its options and progress, and resumes a questionnaire that was already
started. `hidoctor_questionnaire_current` returns the current question
later without changing anything.

**3. Ask and save each answer**

Ask the question as returned, in the patient's language, and offer its
options. Send the patient's own answer with
`hidoctor_questionnaire_answer`; it returns the next question. Repeat
until the result says the questionnaire is complete.

**4. Go back when something needs changing**

`hidoctor_questionnaire_back` returns to an earlier question, grid item
or follow-up without changing any answer. Send the corrected answer with
`hidoctor_questionnaire_answer`. If a change closes a branch, the answers
that no longer apply are dropped and listed in the result.

**5. Review with the patient**

`hidoctor_questionnaire_review` returns every answer as readable text,
plus any required item still missing. Read it back and ask the patient
to confirm.

**6. Submit through an approval link**

`hidoctor_questionnaire_submit` prepares the submission and returns an
`approval_url`. The patient approves it on Hi Doctor. Poll
`hidoctor_operation_get`, then commit with the same arguments,
`confirmation_id` and an `idempotency_key`.

A committed submission has one of three outcomes: `submitted` (sent to a
doctor for review), `ineligible` (a clinical result; never re-answer to change
it) or `covered_by_active_plan` (the patient's plan already covers it).

### Which answer formats does the questionnaire accept?

The MCP tools accept the same answer bodies as the REST questionnaire, so the
shapes are documented once, in the
[questionnaire guide](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md):

| What you need | Where it is described |
| - | - |
| A single, multiple-choice, input or grid answer | [Send an answer](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#send-an-answer) |
| Skip an optional question | [Skip an optional question](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#skip-an-optional-question) |
| One grid row (`values_key`) or follow-up (`option_input_key`) | [Answer one grid item or follow-up](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#answer-one-grid-item-or-follow-up) |
| Several answers at once in `answers` | [Send a batch](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#send-a-batch) |
| `expected_revision` and stale drafts | [Revisions and conflicts](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#revisions-and-conflicts) |

Two points are specific to the connector:

* **Optional revision check.** `expected_revision` is optional in
  `hidoctor_questionnaire_answer`. Without it, the tool uses the revision it
  has just read. Pass it from the previous result when the patient may also be
  editing on hi-doctor.ai.
* **Older categories.** Skips, batches, `expected_revision` and single grid or
  follow-up answers need the guided questionnaire. A category that does not
  offer it returns `guided_api_required`; answer one whole question at a time
  instead.

The assistant rules for questionnaires are on
[Build on Hi Doctor with AI](https://docs.hi-doctor.ai/mcp/ai-integration.md).

## Pay for a consultation

Checkout is completed on hi-doctor.ai, not through the connector.
`hidoctor_checkout_create` can prepare a checkout and show it for approval,
but its commit returns `backend_atomicity_required`. Tell the patient this
before they approve anything.

**1. Confirm what the patient is requesting**

Agree the treatment, dose and plan (`one_off` or `subscription`) the
patient wants to request. The doctor decides whether it is appropriate.

**2. Send the patient to hi-doctor.ai**

The patient signs in on hi-doctor.ai, reviews the treatment, plan and
amount, and pays on Stripe's page. Card details are never entered in chat.

**3. Optionally show the checkout first**

If the patient wants to see the amount in the conversation,
`hidoctor_checkout_create` with `treatment_id`, `dosage` and `plan`
prepares it and returns an `approval_url`, or lists missing profile
fields. Committing it returns `backend_atomicity_required`, and nothing is
charged.

**4. Confirm the payment**

After the patient pays, `hidoctor_consultations_list` shows the new
consultation. If you hold a checkout `session_id`,
`hidoctor_checkout_status` reports whether it was paid. It can finalise a
paid session and create the consultation, so call it once, not in a loop.

> [!WARNING]
>
> Do not tell the patient that a checkout is paid or complete because a tool
> returned an `approval_url`. Payment happens only on hi-doctor.ai, through
> Stripe. See
> [Actions that cannot complete yet](https://docs.hi-doctor.ai/mcp/approvals.md#actions-that-cannot-complete-yet).

## Get a prescription or invoice

1. `hidoctor_prescriptions_list` or `hidoctor_payments_list` to find the right
   record.
2. `hidoctor_prescription_pdf` or `hidoctor_payment_invoice` for the
   document. The result is a link and metadata, never the PDF bytes. Its
   `delivery` field says how the link opens; a `signed_redirect` link opens
   without signing in.
3. Treat the document as confidential: give it only to the patient, never
   repeat it in a shared place, and do not store it.

For a refund, `hidoctor_payment_credit_note` returns the credit note the same
way. If a prescription expired or was lost,
`hidoctor_prescription_request_reissue` prepares a request to the medical
team; the request itself is completed on hi-doctor.ai. How prescriptions reach
a pharmacy is explained on [How it works](https://docs.hi-doctor.ai/essentials/how-it-works.md).

## Message the medical team

**1. Check for replies**

`hidoctor_messages_unread_summary` shows whether there are unread
replies. `hidoctor_messages_get_thread` reads the conversation without
creating it or marking it read.

**2. Open the conversation if needed**

If the patient has no conversation yet, `hidoctor_conversation_open`
creates it, or reuses the existing one.

**3. Prepare the exact text**

Agree the wording with the patient, then call `hidoctor_message_send`
with `content`. It returns an `approval_url`.

**4. Approve and commit**

The patient approves the exact text on Hi Doctor. Poll
`hidoctor_operation_get`, then commit with the same `content`,
`confirmation_id` and an `idempotency_key`. After a timeout, repeat the
commit with the same key; never prepare the message again.

**5. Mark as read**

`hidoctor_messages_mark_read` marks the conversation as read once the
patient has seen the replies.

### How do I send a file to the medical team?

Upload the file first through the connector's file upload, which returns a
`file_ref`: a short reference to the uploaded file that tools accept instead
of the file's bytes. Then prepare `hidoctor_message_attachment_send` with that
`file_ref` and an optional caption, and follow the same approval steps.
`hidoctor_message_attachment_get` returns an attachment as a link. File
uploads need an MCP client that supports them.

## Keep the progress journal

Start with `hidoctor_progress_status`: it says whether the journal is enabled,
needs an active subscription, or is unavailable. The journal is offered with
weight-loss treatment.

| Entry | How it behaves |
| - | - |
| Weight | One entry per day. `hidoctor_progress_weight_log` replaces the entry for that date, using today in the profile's time zone if no date is given. |
| Injections | Each call to `hidoctor_progress_injection_log` creates a new entry. The time needs a time-zone offset. |
| Notes | Each call to `hidoctor_progress_note_log` creates a new entry, even on the same day. |
| Injection plan | `hidoctor_progress_plan_set` takes the preferred time as `HH:MM`. The older values `morning`, `afternoon` and `evening` are stored as 09:00, 14:00 and 19:00. |

To correct an entry, call `hidoctor_progress_day_get` for the day; it returns
each entry's ID for the update tools. Deleting an entry is completed on
hi-doctor.ai. The older names `hidoctor_progress_injections_log` and
`hidoctor_progress_notes_add` still run for now but are hidden from the tool
list; update saved prompts to the new names (see
[Patient tools](https://docs.hi-doctor.ai/mcp/tools/patient.md)).

## Manage a subscription

* `hidoctor_subscription_get` shows each plan and the end of its current
  period.
* `hidoctor_subscription_cancel` prepares cancellation of one plan, by
  `subscription_id`, for the **end of the paid period**, never immediately.
  `hidoctor_subscription_reactivate` undoes it before that date. Both use an
  approval link.
* `hidoctor_subscription_billing_portal` returns a confidential Stripe link
  for card, plan and billing details.
* `hidoctor_subscription_early_order` brings the next refill forward. It
  creates the renewal consultation now, is allowed once per paid period and
  **cannot be undone**. Explain that and get an explicit yes before preparing
  it; the patient then approves it through the approval link.
* When a renewal consultation is waiting for the patient's choice,
  `hidoctor_renewal_get` with `action: "pending"` shows it, and
  `hidoctor_renewal_confirm` prepares the patient's choice for approval.

Fees and refunds are explained on [Pricing](https://docs.hi-doctor.ai/essentials/pricing.md).

## Report a side effect

`hidoctor_adverse_event_report` sends a suspected side effect to the clinical
team for review. Ask for each detail (medicine, what happened, severity, when
it started) instead of guessing. It is not an emergency channel: for severe or
sudden symptoms, tell the patient to contact their local emergency number. See
[Safety](https://docs.hi-doctor.ai/essentials/safety.md).

## Lists and pagination

List tools take `limit` and `offset` and a `detail` mode:

| Mode | What it returns |
| - | - |
| `detail: "concise"` (default) | A short summary of each row, up to 50 rows, with `total_count`, `has_more` and `next_offset`. |
| `detail: "full"` | The page as the Hi Doctor API sends it, with every field and the API's own `count`. |

When `has_more` is true, call the same tool again with `offset` set to
`next_offset`, keeping the same filters and ordering, until `has_more` is
false. With `detail: "full"`, keep raising `offset` by `limit` until `count` is
reached. To count or add up rows, for example "how much have I paid in total",
page to the end before you add anything.

Results are also capped in size, in both modes. If a page is too large to
return whole, the server returns fewer rows with `truncated: true`, `has_more`
and a `next_offset`; it never cuts a row in half. A single record that does
not fit returns a `result_too_large` error: ask for a smaller `limit`.

## Frequently asked questions

### Can an assistant answer the questionnaire for the patient?

No. The assistant asks each question as returned and records only what the patient said. Hi Doctor's servers cannot tell whether an answer came from the patient, so the assistant must never pick, infer or suggest an answer.

### What does an ineligible questionnaire result mean?

It is a clinical result, not an error. Explain it plainly and do not send different answers to change it. The patient can message the medical team with questions.

### Can a patient pay for a consultation through the connector?

No. Checkout is completed on hi-doctor.ai, and payment happens on Stripe's page. The connector can show a prepared checkout for approval, but its commit returns backend\_atomicity\_required and nothing is charged.

### Why is a prescription or invoice not attached to the result?

Document tools return a link and metadata, never the PDF itself. Treat the link as confidential, give it only to the patient and do not store it.

### What happens if a commit times out?

Repeat the same commit with the same confirmation ID, arguments and idempotency key. Hi Doctor checks what happened and never runs the action twice. Never prepare the action again to escape a pending state.

### Why does logging a weight replace the earlier entry?

The journal keeps one weight per day, so logging a weight for a date replaces that day's entry. Injections and notes work differently: each call adds a new entry.

### How do I get every row of a long list?

Call the same list tool again with offset set to next\_offset until has\_more is false. Page to the end before counting or adding anything up.

## Next steps

* [Build on Hi Doctor with AI](https://docs.hi-doctor.ai/mcp/ai-integration.md): the system prompt and rules an assistant must follow.
* [Approval links](https://docs.hi-doctor.ai/mcp/approvals.md): operation states, expiry and safe retries.
* [Patient tools reference](https://docs.hi-doctor.ai/mcp/tools/patient.md): every tool, its permission and its hints.
* [Troubleshooting](https://docs.hi-doctor.ai/mcp/troubleshooting.md): fixes for sign-in, permission and tool errors.

Ready to see a doctor? [Start a consultation on hi-doctor.ai](https://hi-doctor.ai/consultation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.