Hi Doctor HTTP chat integration for your own chat app

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	The patient’s REST access token
Let a model read records, send messages and run tasks for each user	The MCP server, per user	The user’s MCP OAuth tokens

If you use an existing assistant such as Claude or ChatGPT, follow the client guides 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/ or email verification, as Authorization: Bearer <access token>. 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

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 in the questionnaire guide. Always send the option values the server returned, never the translated labels.

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.

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.

How do I connect my chat backend to the MCP server?

Your user ──> your chat backend ──> model API ──> https://mcp.hi-doctor.ai/mcp
                    │                                   │
                    └── OAuth (per user) ───────────────┘

Three rules shape every design:

Each user connects their own Hi Doctor account. Run the OAuth flow described on Streamable HTTP 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.
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.
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.

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, you pass the server URL and the user’s MCP access token with each request:

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.

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.

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

Build on Hi Doctor with AI

The system prompt and assistant rules.

Streamable HTTP

Endpoint, OAuth flow and protocol errors.

Questionnaire guide

Answer formats, skips, batches and revisions.

Security

Tokens, permissions and what the server logs.

Start

Use

Reference

Trust

Updates

Hi Doctor HTTP chat integration for your own chat app

How does the chat questionnaire API work?

Start the questionnaire

Send an answer

Review and submit

Errors and limits

How do I connect my chat backend to the MCP server?

Token handling

Option 1: let the model API call the server

Option 2: run an MCP client in your backend

Handling results

Frequently asked questions

Which token does the chat questionnaire API accept?

Can I call the chat questionnaire API from a browser or a model prompt?

How many requests can I send?

Does submitting through the chat API need the patient’s confirmation?

Can one Hi Doctor connection serve all my users?

Why did a token refresh fail with invalid_grant?

Next steps

Build on Hi Doctor with AI

Streamable HTTP

Questionnaire guide

Security

​How does the chat questionnaire API work?

​Start the questionnaire

​Send an answer

​Review and submit

​Errors and limits

​How do I connect my chat backend to the MCP server?

​Token handling

​Option 1: let the model API call the server

​Option 2: run an MCP client in your backend

​Handling results

​Frequently asked questions

​Which token does the chat questionnaire API accept?

​Can I call the chat questionnaire API from a browser or a model prompt?

​How many requests can I send?

​Does submitting through the chat API need the patient’s confirmation?

​Can one Hi Doctor connection serve all my users?

​Why did a token refresh fail with invalid_grant?

​Next steps

Build on Hi Doctor with AI

Streamable HTTP

Questionnaire guide

Security

How does the chat questionnaire API work?

Start the questionnaire

Send an answer

Review and submit

Errors and limits

How do I connect my chat backend to the MCP server?

Token handling

Option 1: let the model API call the server

Option 2: run an MCP client in your backend

Handling results

Frequently asked questions

Which token does the chat questionnaire API accept?

Can I call the chat questionnaire API from a browser or a model prompt?

How many requests can I send?

Does submitting through the chat API need the patient’s confirmation?

Can one Hi Doctor connection serve all my users?

Why did a token refresh fail with invalid_grant?

Next steps