Agent quickstart: connect Hi Doctor MCP and guide a patient

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

How does an agent connect and authorise?

Read connect and Streamable HTTP. Use the unauthenticated challenge’s resource_metadata URL to discover the protected resource and its authorisation server.
Read the authorisation server metadata. Use its deployed registration mechanism and PKCE with S256; do not assume client ID metadata documents are supported.
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.
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.

tools/list result (excerpt)

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

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

Committed submission, ineligible

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

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, permissions and the ten 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. 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: payments, documents, messages and plans step by step.
Approval links: states, expiry and commit rules.
Patient tool reference: every patient tool, its inputs and annotations.
What is MCP?: the protocol explained in plain terms.

Get started

Service

Integrate Hi Doctor

Partner with Hi Doctor

For AI agents

Agent quickstart: connect Hi Doctor MCP and guide a patient

How does an agent connect and authorise?

What does tools/list return?

What is a safe first read?

How does an agent guide a questionnaire?

What does an ineligible result look like?

Who does what after submission?

How should an agent handle errors?

Frequently asked questions

Which MCP server should the agent connect to?

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

Does submitting a questionnaire mean the treatment is approved?

Why does questionnaire submit return an approval link?

What should the agent do if the result is ineligible?

Can the agent read the medical team conversation safely?

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

Next steps

​How does an agent connect and authorise?

​What does tools/list return?

​What is a safe first read?

​How does an agent guide a questionnaire?

​What does an ineligible result look like?

​Who does what after submission?

​How should an agent handle errors?

​Frequently asked questions

​Which MCP server should the agent connect to?

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

​Does submitting a questionnaire mean the treatment is approved?

​Why does questionnaire submit return an approval link?

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

​Can the agent read the medical team conversation safely?

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

​Next steps

How does an agent connect and authorise?

What does tools/list return?

What is a safe first read?

How does an agent guide a questionnaire?

What does an ineligible result look like?

Who does what after submission?

How should an agent handle errors?

Frequently asked questions

Which MCP server should the agent connect to?

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

Does submitting a questionnaire mean the treatment is approved?

Why does questionnaire submit return an approval link?

What should the agent do if the result is ineligible?

Can the agent read the medical team conversation safely?

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

Next steps