> ## 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. # Streamable HTTP and OAuth for any MCP client > Connect any MCP client or your own code to Hi Doctor: endpoint, protocol versions, OAuth discovery, PKCE, token lifetimes, limits and errors. Hi Doctor is a remote MCP server at `https://mcp.hi-doctor.ai/mcp` that uses the Streamable HTTP transport with OAuth 2.1 authorization. Use this page when your client has no dedicated guide or when you write your own MCP client. It is also the reference for token lifetimes, rate limits and result size limits. Last reviewed: 2026-11-04 ## Endpoint | | | | - | - | | MCP endpoint | `POST https://mcp.hi-doctor.ai/mcp` | | Transport | Streamable HTTP, stateless: each POST is handled on its own and no `Mcp-Session-Id` is issued | | Requests | JSON-RPC 2.0 in the POST body, `Content-Type: application/json` | | Accept | Send `Accept: application/json, text/event-stream`; read the reply either as JSON or as a single-request SSE stream | | Authorization | `Authorization: Bearer ` issued by Hi Doctor's authorization server | | Not supported | `GET` and `DELETE` on `/mcp` and `/` (HTTP 405), the legacy HTTP+SSE transport (`/sse`), stdio, and client ID metadata documents | `POST https://mcp.hi-doctor.ai` (no path) is an alias of the same resource: tokens bound to `/mcp` work there too. `/mcp` is the canonical resource; use it in configuration and as the OAuth `resource` value, never the no-path form. `GET https://mcp.hi-doctor.ai/healthz` needs no token and returns the service status. ## Protocol versions The server uses the legacy `initialize` handshake and negotiates these protocol versions: `2025-11-25` (latest), `2025-06-18`, `2025-03-26`, `2024-11-05` and `2024-10-07`. The [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) removes `initialize` and protocol sessions and adds `server/discover`. Hi Doctor does not support the 2026-07-28 protocol; clients that support both should fall back to a 2025 version. Any change is announced in the [changelog](https://docs.hi-doctor.ai/mcp/changelog.md). ## Authorization Hi Doctor's MCP server is both the OAuth authorization server and the protected resource. Sign-in itself is delegated to hi-doctor.ai, as described on [Connect](https://docs.hi-doctor.ai/mcp/connect.md). | Step | Detail | | - | - | | Challenge | A request without a valid token gets HTTP 401 with `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://mcp.hi-doctor.ai/.well-known/oauth-protected-resource/mcp", scope="…"`. `scope` lists every scope the server supports. Request it as given: Hi Doctor grants the ones a patient account can hold (the seven below) and drops the rest | | Step-up | A valid token without the permission a tool needs gets HTTP 403 with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…", resource_metadata="…"`. `scope` lists the permissions to request: those already granted plus the missing one | | Protected resource metadata (RFC 9728) | `https://mcp.hi-doctor.ai/.well-known/oauth-protected-resource/mcp` (also served without the `/mcp` suffix) | | Authorization server metadata (RFC 8414) | `https://mcp.hi-doctor.ai/.well-known/oauth-authorization-server` | | Client registration | Dynamic client registration (RFC 7591) at `POST /register`, public clients only (`token_endpoint_auth_method: none`). Client ID metadata documents are not supported | | Authorization | `GET /authorize` with `response_type=code`, PKCE `code_challenge_method=S256` (required; `plain` is rejected), `state` and `resource=https://mcp.hi-doctor.ai/mcp` | | Authorization response | The redirect carries `code` and `state`, plus `iss=https://mcp.hi-doctor.ai` (RFC 9207). Error redirects carry `iss` too. Check that it matches the issuer in the authorization server metadata | | Redirect URIs | Must exactly match a URI registered for the client. Loopback redirects may use any port (RFC 8252) | | Token | `POST /token` with `authorization_code` or `refresh_token` grants | | Revocation (RFC 7009) | `POST /revoke` with `token=`. Revokes the whole connection: every token from it is rejected on the next request. Answers HTTP 200 even for an unknown or expired token | | Scopes a patient account can hold | `hidoctor:profile`, `hidoctor:consultations`, `hidoctor:messages`, `hidoctor:questionnaires`, `hidoctor:checkout`, `hidoctor:progress`, `hidoctor:records:write`. The metadata's `scopes_supported` and the 401 challenge list more; scopes that do not apply to a patient account are dropped at grant time | ### Token lifetimes and rotation * Authorization codes are single-use and expire after 60 seconds. * Access tokens last at most one hour. * Refresh tokens last 30 days and are single-use: each refresh returns a new one, and reusing an old one fails with `invalid_grant`. * Each token is bound to the `/mcp` resource and rejected anywhere else. * A revoked connection's tokens are rejected at once, whatever their expiry. If you request no scopes, the patient defaults apply. Requested scopes that do not apply to the account are dropped. See [Permissions](https://docs.hi-doctor.ai/mcp/permissions.md#defaults). > [!WARNING] > > Only tokens issued by this authorization server are accepted. A Hi Doctor REST > API token (from `/v1/users/token/`) is not an MCP token and must never be sent > to the MCP endpoint, and an MCP token is never forwarded to the REST API by > your client. Call the revocation endpoint when the user removes your client's connection, so access ends at once instead of when the access token expires. ### Step-up for a missing permission When a client calls a tool whose permission the user did not approve, the server answers with HTTP 403 before the tool runs. Start a new authorization with the `scope` value from the challenge, let the user approve it, and repeat the call with the new token. A client that does not support step-up should tell the user to disconnect and connect again. ## A minimal session Every request is a separate POST with the bearer token. Replace `$HD_MCP_TOKEN` with an access token your client obtained through OAuth; do not paste tokens into shared logs. **1. Initialize** ```bash theme={null} curl -sS https://mcp.hi-doctor.ai/mcp \ -H "Authorization: Bearer $HD_MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}' ``` The result includes the negotiated `protocolVersion`, the server's capabilities and short `instructions` for the account. Send `MCP-Protocol-Version` with the negotiated version on later requests. **2. List tools** ```bash theme={null} curl -sS https://mcp.hi-doctor.ai/mcp \ -H "Authorization: Bearer $HD_MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2025-06-18" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` You receive only the tools for the account and its approved scopes. **3. Call a read-only tool** ```bash theme={null} curl -sS https://mcp.hi-doctor.ai/mcp \ -H "Authorization: Bearer $HD_MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2025-06-18" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hidoctor_profile_get","arguments":{}}}' ``` Results carry `structuredContent` that matches the tool's output schema, plus the same data as JSON text for clients that only read text. A result is capped at about 20,000 tokens; larger lists come back shorter with `has_more` and `next_offset`. See [Lists and pagination](https://docs.hi-doctor.ai/mcp/workflows.md#lists-and-pagination). ## Limits | Limit | Value | | - | - | | MCP requests per access token | 120 a minute (fixed window). Over the limit: HTTP 429 with `Retry-After` | | Token requests per address | 30 a minute. Over the limit: HTTP 429 `{"error":"slow_down"}` with `Retry-After` | | Request body | 1 MB | | Tool result size | About 20,000 tokens. Lists come back shorter with `has_more` and `next_offset` | | Approval link | Valid for 15 minutes; receipts readable for 30 days. See [Approval links](https://docs.hi-doctor.ai/mcp/approvals.md) | ## Errors | Situation | Response | | - | - | | Missing, expired or invalid token | HTTP 401 with the `WWW-Authenticate` challenge above. Refresh, or sign in again | | More than 120 requests a minute with one token | HTTP 429 with `Retry-After`. Wait before retrying | | More than 30 token requests a minute from one address | HTTP 429 `{"error":"slow_down"}` with `Retry-After` | | `GET` or `DELETE` on `/mcp` or `/` | HTTP 405 | | Unknown tool | JSON-RPC error `-32602` (invalid params) | | A tool that is not available to the account | HTTP 403 `{"error":"forbidden"}`. Consent cannot add it | | Tool whose permission was not approved | HTTP 403 `insufficient_scope` step-up challenge, described above | | Result too large to return, even in part | Tool result with `isError: true` and code `result_too_large`. Ask for fewer rows or a shorter date window | | Validation, not found, conflict or upstream failure | Tool result with `isError: true` and `structuredContent.error` containing `code`, `message` and, where useful, `field`, `hint` or `missing_fields` | Tool errors are designed for the model to read and recover from. Retry reads after a pause; do not repeat a write until you have read the current state. ## Related reading * [Security](https://docs.hi-doctor.ai/mcp/security.md): how tokens and permissions are enforced. * [Troubleshooting](https://docs.hi-doctor.ai/mcp/troubleshooting.md): sign-in and connection problems. * [MCP transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) and [authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) in the specification. ## Frequently asked questions ### Which MCP transport does Hi Doctor use? Streamable HTTP, stateless. Each POST to [https://mcp.hi-doctor.ai/mcp](https://mcp.hi-doctor.ai/mcp) is handled on its own, and the legacy HTTP+SSE transport and stdio are not supported. ### Which MCP protocol versions does Hi Doctor support? 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07, negotiated through the initialize handshake. The 2026-07-28 protocol is not supported. ### How long do Hi Doctor MCP tokens last? Access tokens last at most one hour. Refresh tokens last 30 days and are single-use, and authorization codes expire after 60 seconds. ### Can I revoke a Hi Doctor MCP token? Yes. POST the token to /revoke. The whole connection is revoked and every token from it is rejected on the next request. ### Can I send a Hi Doctor REST API token to the MCP endpoint? No. Only tokens issued by the MCP authorization server are accepted, and an MCP token must never be sent to the REST API. ### What happens when a tool needs a permission the user did not approve? The server answers HTTP 403 with an insufficient\_scope challenge. Start a new authorization with the scope it names, then repeat the call. ### What is the rate limit? 120 MCP requests a minute per access token and 30 token requests a minute per address, each counted in a fixed one-minute window. Over the limit, wait for the Retry-After value. ## Next steps * [Agent quickstart](https://docs.hi-doctor.ai/ai/quickstart.md): a complete agent flow from connection to first tool call. * [Security](https://docs.hi-doctor.ai/mcp/security.md): how tokens and permissions are enforced. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.