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

# How we designed the Hi Doctor MCP server

> Design choices behind the Hi Doctor MCP server: clinical boundaries, scopes, token budgets, continuation and errors, and how we tested them.

The Hi Doctor MCP server is an interface whose main user is a language model,
so it was designed around how models read tools: names, descriptions, schemas
and results all become context. This article explains the choices behind it,
from the clinical boundary and scopes to token budgets, continuation and
errors, and what our own evaluation found before the 6 October 2026 update
reached patients.

Last reviewed: 2026-11-04

A model reads every tool definition before it reads the user's request,
chooses tools from their names and descriptions, and treats whatever a tool
returns as context for its next step. In healthcare, a wrong choice is not
just a failed request: a guessed answer can end up in the record a doctor
prescribes from. If you want to use the connector rather than build on it,
start with [Connect Hi Doctor to your AI assistant](https://docs.hi-doctor.ai/blog/connect-hi-doctor-mcp.md).

## Start from the clinical boundary

The first decision was what the server must never do. Every consultation is
reviewed in full by an EU-licensed doctor, who decides on medical grounds only
(see [Safety](https://docs.hi-doctor.ai/essentials/safety.md)). No tool available to a patient approves a
consultation, issues or changes a prescription, or changes a dose. Those
actions are not hidden behind a permission; they are absent. Eligibility
checks stay on Hi Doctor's servers, which run them the same way on every
interface.

Everything else follows from that line. The assistant's job in a consultation
is to help the patient say what is true, one question at a time, so the
questionnaire tools return one question, record one answer, read the answers
back, and submit only when asked. The server decides which question comes
next, so the model never evaluates a clinical condition itself.

Data that could steer a patient towards eligibility does not belong in a
model's context at all. Questionnaire results expose only the fields needed to
ask the question and record the answer; answer-evaluation metadata is removed
from every questionnaire output rather than accompanied by an instruction to
ignore it.

## Scopes decide what a connection gets

OAuth scopes decide which groups of tools a connection gets: profile,
consultations, messages, questionnaires, payment and health tracking, with
separate write scopes for changes. A tool whose scope was not granted is not
listed. Every tool reaches only what Hi Doctor's API already lets that account
see; the server adds no access of its own.

## Fewer, clearer tools

Anthropic's guidance on [writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
and the [Claude connector review criteria](https://claude.com/docs/connectors/building/review-criteria)
point the same way: a small set of clearly separated tools, reads separate from
writes, and descriptions that state facts rather than instruct the model.

We applied that conservatively. Reads and writes stay separate tools, and
create, update and delete stay distinct, because a catch-all tool with a
hidden destructive branch is worse for safety than one extra entry in the
list. Where names were inconsistent, the new name is listed and the old one
keeps working for a transition period, so existing clients do not break. Tools
would only be merged or hidden if a measured selection test showed real
overlap within the same safety class; a tool that is rarely chosen is a
candidate for review, not proof that it is redundant. The test did not show
that overlap on the look-alike pairs we declared in advance, so the catalog
kept the same number of tools and the work went into names, descriptions and
schemas.

Every tool carries a human title and honest hints: whether it only reads,
changes data, is destructive, is safe to repeat, or reaches Stripe. Clients use
those hints to decide when to ask the user. Hints are a courtesy to the
client, never a substitute for the server's own checks.

## A budget for the catalog

The tool list is paid for on every turn. We set a hard budget for the patient
catalog: at most 20,000 tokens for the complete `tools/list` response,
counted with the `cl100k_base` tokenizer (a stated proxy, not any provider's
billing count), including output schemas.

| Patient `tools/list` as of 6 October 2026 (50 tools) | Before | After |
| - | -: | -: |
| Tokens (`cl100k_base`) | 42,063 | 19,974 |
| Serialized size (characters) | 209,956 | 87,513 |

On 6 October 2026 the patient catalog landed at 19,974 tokens against a budget
of 20,000, which is why the budget is enforced by a test rather than left as a
target. The catalog has grown since, so these figures describe that snapshot;
the test is the current guarantee, and the current list is in the
[patient tools reference](https://docs.hi-doctor.ai/mcp/tools/patient.md).

Most of the savings come from schemas, not prose. Repeated output schemas for
the questionnaire tools were the largest single cost. We narrowed schemas
where the data allowed it, but never dropped a required structured result or
weakened validation to hit the number.

## A budget for every result

A tool result is also context. Every result, counting both the structured
data and its text copy, is capped at 100,000 characters and 20,000
`cl100k_base` tokens, below the limits published for hosted Claude clients and
Claude Code. When a list would exceed the cap, the server returns the longest
complete prefix that fits, says so, and gives the exact offset to continue
from. A single record too large to return becomes an error that explains how
to narrow the request. Nothing is cut in the middle of a value, and totals are
never silently changed.

Before the change, some results were far over that cap. After it, every
result either fits the cap or comes back as a prefix with a continuation
offset, or as an error that explains how to narrow the request.
A cap alone is not enough, though: a bounded error protects the context
window but does not answer the question, so after testing the cap was adjusted
until ordinary reads, such as a single consultation, fit within it.

## Continuation that does not lose rows

Lists default to a concise form, because a short summary per row is usually
what the next step needs. The earlier concise form showed at most five rows of
a page, which made it easy for a model to sum five payments and report them as
the total. Concise lists now honour the requested limit, report how many rows
came back, whether there are more, and the next offset to request.

## Errors a model can act on

Validation, conflict and refusal errors come back as tool results with a
stable `code`, a readable message, and the field or missing fields to fix, so a
model can correct itself or ask the user. Raw error text and upstream traces
are never passed through. Authorization failures are handled at the HTTP
layer, so clients can start sign-in or ask for a missing permission instead of
seeing a generic failure.

## How we measured it

Deterministic tests cover the contract: every tool definition, scope
enforcement, privacy filters, budgets and continuation. They prove the server
behaves as specified; they say nothing about whether a model picks the right
tool. For that we also ran real agents on test accounts with synthetic data,
checking which tool they chose, whether multi-step tasks ended with the
account in the expected state, and how each tool handles invalid input, a
missing permission and another account's ID.

The clearest change was the missing-permission case. Before, a missing
permission came back as a tool error; now it is an HTTP 403 challenge that
names the permission, so a client can ask the person to approve it.

These checks use synthetic patients and one agent family, so they describe
how this server behaves rather than make a general claim about every model or
client.

## What is not supported?

As of 4 November 2026, the connector does not support the 2026-07-28 version
of the MCP specification or client ID metadata documents. Every client we
target supports dynamic registration. Changes are recorded in the
[changelog](https://docs.hi-doctor.ai/mcp/changelog.md).

## Frequently asked questions

### Can a Hi Doctor MCP tool approve a consultation or prescribe?

No. Those tools do not exist for patients. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only.

### How does the server limit what an assistant can reach?

OAuth scopes decide which groups of tools a connection gets, and a tool whose scope was not granted is not listed. Every tool reaches only what Hi Doctor's API already lets that account see.

### Why does the catalog have a token budget?

The tool list is sent to the model on every turn, so its size is a cost on every request. A test fails if the patient tools/list response grows past 20,000 cl100k\_base tokens.

### What happens when a result is too large?

The server returns the longest complete prefix that fits the result budget, says so, and gives the offset to continue from. Nothing is cut in the middle of a value.

### How was the server tested?

Deterministic tests cover the contract, and real agents ran tasks on test accounts with synthetic data. The results describe this server, not every model or client.

## Next steps

> [card] [Privacy and security of the Hi Doctor MCP](https://docs.hi-doctor.ai/blog/privacy-security-hi-doctor-mcp.md)
>
> Sign-in, tokens, consent and confidential links.

> [card] [Patient tools reference](https://docs.hi-doctor.ai/mcp/tools/patient.md)
>
> Every patient tool, its scope and its hints.

> [card] [MCP or REST for healthcare integrations](https://docs.hi-doctor.ai/blog/mcp-vs-rest-for-healthcare-integrations.md)
>
> Which Hi Doctor surface fits your product.

> [card] [Streamable HTTP](https://docs.hi-doctor.ai/mcp/streamable-http.md)
>
> Transport and OAuth reference for client builders.


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