> ## 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.

# Approval links for Hi Doctor MCP actions

> How Hi Doctor MCP tools prepare an action, wait for the patient to approve it on Hi Doctor, and commit it exactly once with safe retries.

An approval link is how a Hi Doctor MCP tool turns an assistant's request into an action the patient has agreed to. The tool prepares the exact action, the patient signs in on Hi Doctor and approves or declines it, and only then can the assistant commit it, once. Sending a message, submitting a questionnaire and cancelling a plan all follow this pattern.

Last reviewed: 2026-11-04

This page is for integrators building on the connector. Tools that use
approval links are marked **Approval link** in the
[patient reference](https://docs.hi-doctor.ai/mcp/tools/patient.md), and the permissions they need are on
[Permissions](https://docs.hi-doctor.ai/mcp/permissions.md).

## The flow

**1. Prepare the action**

Call the tool with its normal arguments. Without `mode`, a call prepares
the action; it does not change anything yet. The result has `state:
        "awaiting_human"`, an `operation_id` (the same value is also returned as
`confirmation_id`), an `approval_url`, `expires_at`, a `preview` of the
exact targets and effects, and a `next_action`.

**2. Give the link to the person**

Show the `approval_url` to the person who owns the connection and ask them
to open it. The link is on `mcp.hi-doctor.ai`. Do not open it for them and
do not describe it as done.

**3. The person signs in and decides**

The person signs in with their own Hi Doctor account on hi-doctor.ai. Hi
Doctor checks that it is the same account that prepared the action, then shows a summary written by Hi Doctor, not by the assistant.
The person selects **Approve** or **Decline**.

**4. Poll the operation**

Call `hidoctor_operation_get` with the `operation_id` until the state is
no longer `awaiting_human`. It returns the state, `expires_at` and the
`next_action`. It never returns the preview or the business result.

**5. Commit with unchanged arguments**

When the state is `approved`, call the same tool again with exactly the
same business arguments, plus `mode: "commit"`, the `confirmation_id`
and an `idempotency_key`. Hi Doctor checks the arguments against what was
approved, checks that the target has not changed, and runs the action
once.

```json Commit call (arguments) theme={null}
{
  "content": "The injection site has been sore since Monday.",
  "mode": "commit",
  "confirmation_id": "0b8c6a4e-2f1d-4c3a-9e57-6d2b1f0a9c11",
  "idempotency_key": "msg-2026-10-07-sore-site"
}
```

> [!NOTE]
>
> Approval links work only on connections made on or after 7 October 2026.
> Older connections receive `reconnect_required`: disconnect and connect again. See
> [What changes for existing connections](https://docs.hi-doctor.ai/mcp/permissions.md#what-changes-for-existing-connections).

## How long does an approval link last?

An approval link is valid for **15 minutes** from preparation. Within that
time the person can restart sign-in from the same link if it timed out.
After the deadline, an operation that was not committed reports `expired`
and cannot run. Prepare the action again and send the new link.

A committed operation's receipt stays readable for 30 days, as long as the
connection is still authorised.

## Operation states

| State | Meaning | What to do |
| - | - | - |
| `awaiting_human` | Prepared; the person has not decided yet. | Wait. Poll `hidoctor_operation_get`. Remind the person if needed. |
| `approved` | The person approved this exact action. | Commit with unchanged arguments, `confirmation_id` and an `idempotency_key`. |
| `declined` | The person declined. | Stop. Do not prepare the same action again unless the person asks. |
| `expired` | The 15 minutes passed before commit. | Prepare again only if the person still wants the action. |
| `executing` | The commit is running. | Repeat the same commit call later to read its outcome. Do not start another action. |
| `uncertain` | The outcome could not be confirmed, for example after a timeout. | Repeat the same commit call with the same key. Hi Doctor checks what happened; it never runs the action twice. |
| `succeeded` | The action ran. | Report the result. Repeating the commit returns the same result. |
| `failed` | The action did not run, and Hi Doctor confirmed it. | Report the error. Ask the person before preparing a new action. |

## How do I retry safely?

Networks fail. The rules below make a retry safe instead of a duplicate.

* **Choose the key before the first commit.** An `idempotency_key` is 8 to
  128 letters, digits, `_` or `-`. Use one key per approved operation and
  keep it until the operation is finished.
* **Retry with the same key and arguments.** After a timeout or a lost
  response, call commit again with the same `confirmation_id`, arguments and
  key. If the action already ran, you get the original result back. If it is
  still running or uncertain, you get its state and guidance, and nothing
  runs again.
* **Never re-prepare to escape a pending state.** A new preparation is a new
  operation. If the first one actually ran, the action would happen twice.
  While an operation is `awaiting_human`, `executing` or `uncertain`, keep
  following that operation.
* **Different key, same confirmation.** Hi Doctor rejects it with
  `confirmation_consumed`.
* **Same key, different operation.** Hi Doctor rejects it with
  `idempotency_conflict`.

Hi Doctor passes each operation to its API with its own `Idempotency-Key`,
so a repeated request is recognised end to end. The API side is described in
the [idempotency guide](https://docs.hi-doctor.ai/api-reference/idempotency.md).

A successful result proves that Hi Doctor recorded the action. For actions
that reach outside Hi Doctor, such as a message to the medical team or a plan change through Stripe, it
does not prove delivery or settlement. Read the resulting record before
telling the person that something arrived.

## Errors

| Code | Meaning |
| - | - |
| `confirmation_required` | The person has not approved this action yet. |
| `confirmation_declined` | The person declined. It cannot be committed. |
| `confirmation_expired` | The 15 minutes passed. Prepare again. |
| `confirmation_arguments_changed` | The commit arguments differ from what the person approved. |
| `confirmation_stale` | The target changed after the preview. Prepare and review again. |
| `confirmation_consumed` | This approval was already committed with another key. |
| `idempotency_conflict` | This key belongs to another operation. |
| `invalid_idempotency_key` | The key is not 8 to 128 allowed characters. |
| `reconnect_required` | The connection predates approval links. Connect again. |
| `approval_channel_unavailable` | Hi Doctor cannot issue approval links right now. Try later. |
| `backend_atomicity_required` | This action is completed on hi-doctor.ai, not through the connector. See [Actions that cannot complete yet](#actions-that-cannot-complete-yet). |

Every error also carries `retryable`, `state`, `next_action` and a
`correlation_id` to quote when you contact Hi Doctor.

## What can complete today

These tools run the whole flow, from preparation to a committed result:

`hidoctor_message_send`, `hidoctor_message_attachment_send`,
`hidoctor_questionnaire_submit`, `hidoctor_subscription_cancel`,
`hidoctor_subscription_reactivate`, `hidoctor_subscription_early_order`,
`hidoctor_renewal_confirm`, `hidoctor_documents_change` and
`hidoctor_consultation_images_change`.

## Actions that cannot complete yet

The other tools with approval links prepare their action and show it for
approval, but the final commit is not available through the connector. Do
these tasks on hi-doctor.ai instead, and tell the patient before they approve
anything:

`hidoctor_profile_update`, `hidoctor_checkout_create`,
`hidoctor_prescription_request_reissue`, `hidoctor_progress_weight_delete`,
`hidoctor_progress_injection_delete`, `hidoctor_progress_note_delete`,
`hidoctor_referrals_activate`, `hidoctor_account_delete` and
`hidoctor_questionnaire_legacy_submit`.

The [patient reference](https://docs.hi-doctor.ai/mcp/tools/patient.md) marks these tools **Available on
the website**. The [changelog](https://docs.hi-doctor.ai/mcp/changelog.md) records any change.

## What is never automated

> [!WARNING]
>
> * **Approval is always a person.** No tool approves an operation, and an
>   argument such as `confirmed: true` is rejected. Only the account owner,
>   signed in on Hi Doctor, can approve.
> * **Uncertain outcomes are never retried automatically.** Hi Doctor checks
>   the recorded state instead of running the action again.
> * **Medical decisions belong to the doctor.** No approval link approves a
>   consultation, issues a prescription or changes a dose; see
>   [Safety](https://docs.hi-doctor.ai/essentials/safety.md).

## Frequently asked questions

### How long is a Hi Doctor approval link valid?

15 minutes from preparation. After that the operation reports expired and must be prepared again.

### Can the assistant approve an action itself?

No. Only the account owner, signed in on Hi Doctor, can approve. An argument such as confirmed: true is rejected.

### What if the commit times out?

Repeat the same commit call with the same confirmation\_id, arguments and idempotency\_key. Hi Doctor checks what happened and never runs the action twice.

### Can I change the arguments after the person approved?

No. The commit must use exactly the approved arguments, otherwise Hi Doctor returns confirmation\_arguments\_changed. Prepare the action again instead.

### Why does a commit return backend\_atomicity\_required?

That action is approved through the connector but completed on hi-doctor.ai. Tell the patient before they approve, and send them to the website.

### Does succeeded mean a message was delivered?

It means Hi Doctor recorded the action. For actions that reach outside Hi Doctor, read the resulting record before telling the person something arrived.

## Next steps

> [card] [Workflows](https://docs.hi-doctor.ai/mcp/workflows.md)
>
> Approval links inside complete patient tasks.

> [card] [Security](https://docs.hi-doctor.ai/mcp/security.md)
>
> How the approval page authenticates the person.

> [card] [Questionnaire guide](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md)
>
> The guided questionnaire behind the questionnaire tools.

> [card] [Agent quickstart](https://docs.hi-doctor.ai/ai/quickstart.md)
>
> Build an agent that uses approval links end to end.


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