Streamable HTTP and OAuth for any MCP client

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 <access token>` 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 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.

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.

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=<access or refresh 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.

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.

Initialize

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.

List tools

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.

Call a read-only tool

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.

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

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.

Security: how tokens and permissions are enforced.
Troubleshooting: sign-in and connection problems.
MCP transports and 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 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: a complete agent flow from connection to first tool call.
Security: how tokens and permissions are enforced.

Start

Use

Reference

Trust

Updates

Streamable HTTP and OAuth for any MCP client

Endpoint

Protocol versions

Authorization

Token lifetimes and rotation

Step-up for a missing permission

A minimal session

Limits

Errors

Frequently asked questions

Which MCP transport does Hi Doctor use?

Which MCP protocol versions does Hi Doctor support?

How long do Hi Doctor MCP tokens last?

Can I revoke a Hi Doctor MCP token?

Can I send a Hi Doctor REST API token to the MCP endpoint?

What happens when a tool needs a permission the user did not approve?

What is the rate limit?

Next steps

​Endpoint

​Protocol versions

​Authorization

​Token lifetimes and rotation

​Step-up for a missing permission

​A minimal session

​Limits

​Errors

​Related reading

​Frequently asked questions

​Which MCP transport does Hi Doctor use?

​Which MCP protocol versions does Hi Doctor support?

​How long do Hi Doctor MCP tokens last?

​Can I revoke a Hi Doctor MCP token?

​Can I send a Hi Doctor REST API token to the MCP endpoint?

​What happens when a tool needs a permission the user did not approve?

​What is the rate limit?

​Next steps

Endpoint

Protocol versions

Authorization

Token lifetimes and rotation

Step-up for a missing permission

A minimal session

Limits

Errors

Related reading

Frequently asked questions

Which MCP transport does Hi Doctor use?

Which MCP protocol versions does Hi Doctor support?

How long do Hi Doctor MCP tokens last?

Can I revoke a Hi Doctor MCP token?

Can I send a Hi Doctor REST API token to the MCP endpoint?

What happens when a tool needs a permission the user did not approve?

What is the rate limit?

Next steps