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

# Agent quickstart: connect Hi Doctor MCP and guide a patient

> Connect an agent to the Hi Doctor MCP connector, list tools, read a profile and guide a questionnaire through to an approved submission.

This quickstart takes an AI agent from no connection to a submitted questionnaire on the Hi Doctor product MCP, `https://mcp.hi-doctor.ai/mcp`. The patient signs in, approves permissions and approves the submission; the agent only prepares each step. Read the [interface and safety guide](https://docs.hi-doctor.ai/ai/index.md) first, then follow the five stages below.

Last reviewed: 2026-11-04

The docs search MCP at `https://docs.hi-doctor.ai/mcp` only searches public documentation and is not used here. For your own application on the REST API, follow the [API quickstart](https://docs.hi-doctor.ai/api-reference/quickstart.md) instead.

## How does an agent connect and authorise?

1. Read [connect](https://docs.hi-doctor.ai/mcp/connect.md) and [Streamable HTTP](https://docs.hi-doctor.ai/mcp/streamable-http.md). Use the unauthenticated challenge's `resource_metadata` URL to discover the protected resource and its authorisation server.
2. Read the authorisation server metadata. Use its deployed registration mechanism and PKCE with `S256`; do not assume client ID metadata documents are supported.
3. Let the patient sign in and approve the scopes. Request only the permissions the task needs, and never collect a password, email code or token in chat.
4. Send `initialize`, then `tools/list` with the issued MCP token.

The client keeps tokens outside the model context. Never send a REST JWT to the product MCP or an MCP token to the REST API.

## What does tools/list return?

The catalog depends on the scopes the patient approved, so always use the list and schemas returned for that connection. This excerpt shows two read-only tools with the field layout the server uses; descriptions are paraphrased and schemas shortened, so rely on the text your connection returns.

```json tools/list result (excerpt) theme={null}
{
  "tools": [
    {
      "name": "hidoctor_profile_get",
      "title": "Profile get",
      "description": "Reads the signed-in account's profile.",
      "inputSchema": { "type": "object", "properties": {} },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    },
    {
      "name": "hidoctor_questionnaire_categories",
      "title": "Questionnaire categories",
      "description": "Lists the questionnaire categories and their slugs.",
      "inputSchema": { "type": "object", "properties": {} },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    }
  ]
}
```

The full catalog, with which tools need an approval link, is in the [patient tool reference](https://docs.hi-doctor.ai/mcp/tools/patient.md).

## What is a safe first read?

For a patient who asks to check their account, call `hidoctor_profile_get` with `{}`. Show only the fields needed for the request and do not log the response.

## How does an agent guide a questionnaire?

| Stage | Tool and action | Stop condition |
| - | - | - |
| Select | `hidoctor_questionnaire_categories` lists the categories; the patient chooses one | Never choose a treatment or medicine for the patient |
| Start or resume | `hidoctor_questionnaire_start` returns the next question and its options | Identity steps happen in the supported patient flow; photographs go through the protected upload or the website |
| Answer | `hidoctor_questionnaire_answer` saves the patient's answer using option `value`s | Never infer missing medical information |
| Review | `hidoctor_questionnaire_review` reads the answers back; `hidoctor_questionnaire_back` returns to a question the patient wants to change | Get explicit confirmation before submission |
| Submit | `hidoctor_questionnaire_submit` prepares the submission and returns an `approval_url` | The patient approves on Hi Doctor before the agent commits |

After the patient approves, poll `hidoctor_operation_get`, then call `hidoctor_questionnaire_submit` again with the same arguments, `mode: "commit"`, the `confirmation_id` and an `idempotency_key`. [Approval links](https://docs.hi-doctor.ai/mcp/approvals.md) describes each state.

Tool inputs come from the discovered schemas and returned identifiers, never from guessed field names or invented patient records. What happens after a submission, such as a payment link or cover by an active plan, is described in [workflows](https://docs.hi-doctor.ai/mcp/workflows.md); follow that page rather than assuming one fixed order.

## What does an ineligible result look like?

A committed submission returns one of three outcomes: `submitted`, `ineligible` or `covered_by_active_plan`. An ineligible result carries a patient-safe `message` and nothing to pay.

```json Committed submission, ineligible theme={null}
{
  "outcome": "ineligible",
  "message": "Based on your answers, this treatment is not suitable for you."
}
```

The message text above is illustrative; show the patient the message the tool returns. Tell the patient plainly, do not offer checkout, and never change answers to get a different outcome.

> [!WARNING]
>
> `hidoctor_checkout_status` can finalise a paid session and create its consultation, so it is not a harmless polling call. After an uncertain write, follow the recovery guidance below before calling it.

## Who does what after submission?

The patient verifies the account, authorises access, gives and confirms the medical answers, approves the submission and completes any payment. An EU-licensed doctor then reviews the consultation; the review happens after the chat, not during it. Any prescribed medicine is collected from a pharmacy, which charges for it separately.

## How should an agent handle errors?

For `401`, renew authorisation through the client. For `403`, stop and resolve permissions. Never repeat a write blindly after a timeout or a `5xx`: reconcile first, which on the endpoints that document it means resending the same `Idempotency-Key` or looking the key up. See [errors and reconciliation](https://docs.hi-doctor.ai/api-reference/errors.md), [permissions](https://docs.hi-doctor.ai/mcp/permissions.md) and the ten [safety rules](https://docs.hi-doctor.ai/ai/index.md#safety-rules).

## Frequently asked questions

### Which MCP server should the agent connect to?

Connect to the product MCP at [https://mcp.hi-doctor.ai/mcp](https://mcp.hi-doctor.ai/mcp). The docs search MCP only searches public documentation and cannot act on an account.

### Why does tools/list show different tools for different patients?

The catalog depends on the permissions the patient approved at sign-in. Always use the tools and schemas returned for that connection.

### Does submitting a questionnaire mean the treatment is approved?

No. Submission sends the answers for review. An EU-licensed doctor reviews the consultation and makes the medical decision afterwards.

### Why does questionnaire submit return an approval link?

Submission has consequences, so the patient approves the exact action on Hi Doctor first. The agent commits it only after the operation is approved.

### What should the agent do if the result is ineligible?

Tell the patient plainly, show the returned message and stop this attempt. Do not change answers or retry to get a different result.

### Can the agent read the medical team conversation safely?

Yes. hidoctor\_messages\_get\_thread reads the conversation without creating it or marking it read. Sending a message uses an approval link.

### Can the agent reuse a REST API token with the MCP connector?

No. MCP OAuth tokens and REST JWTs are separate credentials, and each works only with its own interface.

## Next steps

* [Workflows](https://docs.hi-doctor.ai/mcp/workflows.md): payments, documents, messages and plans step by step.
* [Approval links](https://docs.hi-doctor.ai/mcp/approvals.md): states, expiry and commit rules.
* [Patient tool reference](https://docs.hi-doctor.ai/mcp/tools/patient.md): every patient tool, its inputs and annotations.
* [What is MCP?](https://docs.hi-doctor.ai/ai/what-is-mcp.md): the protocol explained in plain terms.


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