> ## 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 HTTP chat integration for your own chat app > Run the Hi Doctor questionnaire over plain HTTP from your own chat app, or connect your chat backend to the Hi Doctor MCP server per user. Hi Doctor offers two ways to bring its consultation questionnaire into a chat product you run yourself. The chat questionnaire API is a set of plain HTTP endpoints for apps that already hold a patient's REST session, and the MCP server lets your backend give a model each user's own Hi Doctor tools through OAuth. Pick the first for a scripted chat flow and the second when a model chooses the tools. Last reviewed: 2026-11-04 | You want to | Use | Credential | | - | - | - | | Ask the questionnaire one question at a time in your own chat UI | [The chat questionnaire API](#how-does-the-chat-questionnaire-api-work) | The patient's REST access token | | Let a model read records, send messages and run tasks for each user | [The MCP server, per user](#how-do-i-connect-my-chat-backend-to-the-mcp-server) | The user's MCP OAuth tokens | If you use an existing assistant such as Claude or ChatGPT, follow the [client guides](https://docs.hi-doctor.ai/mcp/overview.md#set-it-up-in-your-client) instead. ## How does the chat questionnaire API work? The chat questionnaire API runs the same one-question-at-a-time questionnaire as the MCP tools, over plain HTTP. Base URL: `https://mcp.hi-doctor.ai/v1/chat/questionnaire` Authenticate with the patient's Hi Doctor REST access token, from [`POST /v1/users/token/`](https://docs.hi-doctor.ai/api-reference/authentication) or email verification, as `Authorization: Bearer `. MCP connector tokens are rejected here, and REST tokens are rejected by the MCP endpoint. Call this API from your server, never from a model prompt. | Method and path | What it does | | - | - | | `GET /categories` | Lists questionnaire categories (paginated: `count`, `next`, `previous`, `results`). Use each result's `slug`. | | `POST /{slug}/start` | Starts or resumes the questionnaire. Optional body `{"locale": "de"}`. | | `GET /{slug}/current` | Returns the current unanswered question without changing answers. | | `POST /{slug}/answer` | Records the patient's answer to one question and returns the next one. | | `POST /{slug}/back` | Returns to an earlier question. Optional body `{"question_key": "...", "locale": "..."}`. | | `GET /{slug}/review` | Returns the saved answers as readable text for read-back. | | `POST /{slug}/submit` | Sends the saved answers to a doctor for review. | Question responses include `question`, `status` (`in_progress` or `ready_to_submit`), `answered_count`, `applicable_total` and `reusable_prefill`. ### Start the questionnaire ```bash theme={null} curl -sS -X POST "https://mcp.hi-doctor.ai/v1/chat/questionnaire/weight-loss/start" \ -H "Authorization: Bearer $HD_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"locale": "fr"}' ``` ### Send an answer The `answer` body takes `question_key` plus one of `value`, `values`, `option_inputs` or `additional_info`. The answer formats are the same as in the REST API; see [Send an answer](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md#send-an-answer) in the questionnaire guide. Always send the option values the server returned, never the translated labels. ```bash theme={null} curl -sS -X POST "https://mcp.hi-doctor.ai/v1/chat/questionnaire/weight-loss/answer" \ -H "Authorization: Bearer $HD_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"question_key": "weight_loss-02-gender", "value": "female"}' ``` ### Review and submit Read the answers from `GET /{slug}/review` back to the patient and get a clear yes. Then submit with an empty body; the saved answers are used. ```bash theme={null} curl -sS -X POST "https://mcp.hi-doctor.ai/v1/chat/questionnaire/weight-loss/submit" \ -H "Authorization: Bearer $HD_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` Submission returns an `outcome` of `submitted` (sent to a doctor), `ineligible` (a clinical result; do not re-answer to change it) or `covered_by_active_plan`. ### Errors and limits Errors use `{"error": {"code", "message", ...}}` with an HTTP status. Client errors carry the same fields as MCP tool errors, such as `next_action` and `correlation_id`. | Status | When | | - | - | | 400 | An invalid answer or body | | 401 `invalid_token` | A missing or wrong token | | 404, 409 | An unknown resource, or a conflict with the current state | | 405 | The wrong method; the `Allow` header names the right one | | 429 `rate_limited` | More than 120 requests a minute per token | | 503, 504 | Hi Doctor's API is unavailable; retry later | Responses are sent with `Cache-Control: no-store`. The rules for running a questionnaire are the same as with MCP: ask each question as written, record only the patient's own answers, read them back, and get a clear yes before submitting. See [Build on Hi Doctor with AI](https://docs.hi-doctor.ai/mcp/ai-integration.md). ## How do I connect my chat backend to the MCP server? ```text theme={null} Your user ──> your chat backend ──> model API ──> https://mcp.hi-doctor.ai/mcp │ │ └── OAuth (per user) ───────────────┘ ``` Three rules shape every design: 1. **Each user connects their own Hi Doctor account.** Run the OAuth flow described on [Streamable HTTP](https://docs.hi-doctor.ai/mcp/streamable-http.md#authorization) for each user, in their browser, so they sign in on hi-doctor.ai and approve the permissions themselves. Never share one account's connection between users. 2. **Tokens stay on your server.** Store the user's MCP access and refresh tokens server-side, encrypted, keyed to that user. Never put a token, a password or a Hi Doctor API credential in a prompt or in model-visible text. 3. **The model asks, the user decides.** Consequential tools (sending a message, submitting a questionnaire, preparing a checkout, ordering a refill early, deleting journal entries) need an explicit "yes" from the user in the conversation before the call, and then the user's own approval through an [approval link](https://docs.hi-doctor.ai/mcp/approvals.md). ### Token handling * Access tokens last at most one hour. Refresh before expiry, or after a 401. * Refresh tokens are **single-use**. Save the new refresh token from every refresh before using the new access token, and make sure two requests for the same user cannot refresh at the same time; the second would fail with `invalid_grant` and the user would have to connect again. * A failed refresh means the user must sign in again. Send them through the OAuth flow; do not retry in a loop. * MCP tokens work only at `https://mcp.hi-doctor.ai/mcp`. Do not send them to the REST API, and do not send REST API tokens to the MCP endpoint. ### Option 1: let the model API call the server Some model APIs can call a remote MCP server for you. With Anthropic's Messages API [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), you pass the server URL and the user's MCP access token with each request: ```python theme={null} import os import anthropic client = anthropic.Anthropic() def ask(user_message: str, hd_mcp_token: str): # hd_mcp_token comes from your server-side token store for this user. return client.beta.messages.create( model=os.environ["MODEL_ID"], max_tokens=2048, system=SYSTEM_PROMPT, # see /mcp/ai-integration messages=[{"role": "user", "content": user_message}], mcp_servers=[{ "type": "url", "url": "https://mcp.hi-doctor.ai/mcp", "name": "hi-doctor", "authorization_token": hd_mcp_token, }], tools=[{"type": "mcp_toolset", "mcp_server_name": "hi-doctor"}], betas=["mcp-client-2025-11-20"], ) ``` The model API connects to Hi Doctor from the provider's infrastructure, so the patient's access token leaves your backend and is held by the model provider for that request. Your backend still owns the OAuth flow and refresh: the provider expects a valid access token on each request. The beta name above is the one in use when this page was reviewed; check the provider's page for the current one and for how to restrict which tools are enabled, and enable only the tools your product needs. > [!WARNING] > > When the provider runs the tools for you, your backend does not see each call > before it happens. Turn off consequential tools in the toolset, or use option 2, > unless your product has another reliable way to get the user's confirmation > first. ### Option 2: run an MCP client in your backend Your backend can connect to Hi Doctor with an MCP client library, list the tools, pass their definitions to the model, and execute the tool calls the model asks for. This gives you a place to: * show the user a confirmation step before any tool that changes data; * filter the tool list to what your product needs; * log which tool ran, without logging medical content or links; * handle `isError` results and pagination consistently. Every request is a stateless POST, so you can open a client per user request. Follow the request format on [Streamable HTTP](https://docs.hi-doctor.ai/mcp/streamable-http.md). ### Handling results * Results contain medical data. Show them only to the user they belong to, and apply your product's data-retention rules. * Prescription and invoice tools return a link, never the document bytes. Show it only to that user, never in a shared view, and do not store it. If the result's `delivery` is `signed_redirect`, the link opens without signing in. * List tools return one page at a time, capped in size, and say how to get the rest (`has_more`, `next_offset`, `how_to_get_more`). Follow them instead of assuming the first page is complete; see [Workflows](https://docs.hi-doctor.ai/mcp/workflows.md#lists-and-pagination). * Tool errors return `structuredContent.error` with a `code`, a `message`, `next_action` and a `correlation_id`, plus sometimes a `hint` or the fields to fix. Let the model read them, but never let it retry a submission or a payment-related call without the user. ## Frequently asked questions ### Which token does the chat questionnaire API accept? Only the patient's Hi Doctor REST access token, sent as a Bearer token. MCP connector tokens are rejected there, and REST tokens are rejected by the MCP endpoint. ### Can I call the chat questionnaire API from a browser or a model prompt? No. Call it from your server, so the patient's access token never reaches a prompt or model-visible text. ### How many requests can I send? The chat questionnaire API allows 120 requests a minute per token. Above that it returns 429 with the code rate\_limited; wait before trying again. ### Does submitting through the chat API need the patient's confirmation? Yes. Read the answers back to the patient and get a clear yes before calling submit. The submission then goes to a doctor for review. ### Can one Hi Doctor connection serve all my users? No. Each user connects their own Hi Doctor account through OAuth in their own browser, and your backend stores each user's tokens separately. ### Why did a token refresh fail with invalid\_grant? Refresh tokens are single-use. If two requests for the same user refresh at once, the second fails and the user must connect again, so save each new refresh token and refresh one request at a time. ## Next steps > [card] [Build on Hi Doctor with AI](https://docs.hi-doctor.ai/mcp/ai-integration.md) > > The system prompt and assistant rules. > [card] [Streamable HTTP](https://docs.hi-doctor.ai/mcp/streamable-http.md) > > Endpoint, OAuth flow and protocol errors. > [card] [Questionnaire guide](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md) > > Answer formats, skips, batches and revisions. > [card] [Security](https://docs.hi-doctor.ai/mcp/security.md) > > Tokens, permissions and what the server logs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.