Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Endpoints

This page lists every HTTP route a server built with app::Server serves: who may call it, what it is for and what it answers, the fields of the two metadata documents, the security headers and the 401 challenge. Every route is at the root of PUBLIC_URL.

Routes

MethodPathAuthenticationPurpose
GET/healthznoneLiveness check: answers ok.
GET/favicon.icononeThe server’s icon, when Server::icon is set.
GET/.well-known/oauth-protected-resource/<service>noneProtected-resource metadata of one service, or of mcp (RFC 9728).
GET/.well-known/oauth-authorization-servernoneAuthorization-server metadata (RFC 8414).
POST/registernoneDynamic client registration (RFC 7591).
GET/authorizenoneThe sign-in page.
POST/authorizethe credential, in the formSigns the person in and redirects to the client with a code.
POST/tokena code and its PKCE verifier, or a refresh tokenIssues access and refresh tokens.
GET/callbackthe pending sign-in’s cookie and stateOnly when people sign in through an upstream provider: where the provider sends them back. Redirects to the client with a code.
POST, GET, DELETE/<service>bearer tokenOne service’s MCP endpoint (Streamable HTTP).
POST, GET, DELETE/mcpbearer tokenEvery service together, while <PREFIX>_COMBINED is true and at least one service is enabled. See Several services and /mcp.
  • A path outside these routes answers 404, for example a service that is not enabled, or /mcp when it is turned off. A known path called with another method answers 405.
  • Routes you add with Server::wrap_router are served as you define them, without the bearer guard, the body limit or the request metrics. Protect them yourself if they need it.
  • Prometheus metrics are served on a separate listener, METRICS_ADDR, not on these routes; see Observability.
  • /healthz, the OAuth routes and the MCP endpoints refuse a request body larger than 1 MiB: with 413 when its Content-Length declares more, and as Body limits describes when it is sent without a declared length.

The MCP endpoints

Each service is mounted at /<service>, and /mcp serves every service’s tools and prompts together. The transport is rmcp’s Streamable HTTP server:

MethodRequestAnswer
POSTA JSON-RPC message, with Content-Type: application/json and Accept: application/json, text/event-stream.The response as JSON or as a server-sent event stream. The answer to initialize carries the new session’s Mcp-Session-Id header, which later requests send back.
GETAccept: text/event-stream and the Mcp-Session-Id header.The session’s stream of server-sent events.
DELETEThe Mcp-Session-Id header.Ends the session: 202.

Sessions exist only on protocol versions before 2026-07-28, where initialize starts one. rmcp serves requests that use the 2026-07-28 revision without a session: for them only POST applies, and GET and DELETE answer 405. When credentials are carried, every session is bound to the credential that opened it; see MCP sessions for the binding and the session caps.

Authentication

Every request needs Authorization: Bearer <token>; the scheme name is case-insensitive. The token is one of:

TokenAccepted when
An access token this server issued for this pathIts grant still holds; see OAuth and tokens. A token for another path is refused.
MCP_AUTH_TOKENIt is set. See The static token.
The person’s own credentialPeople sign in with their own credential and the verifier accepts it as a bearer token. See Credentials sent as bearer tokens.

A request let through carries a Caller and, when credentials are carried, the person’s Credential.

The 401 challenge

A request without a usable token gets 401 Unauthorized with an empty body and a WWW-Authenticate header that names the path’s protected-resource metadata, where an MCP client starts discovery:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/weather"

When a token was sent and refused, the challenge adds error="invalid_token":

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/weather", error="invalid_token"

A token is refused when it is expired, issued for another path, from a grant that has ended, signed under another key, or a wrong static token or credential. The challenge never says which. Troubleshooting explains how to find out.

Responses

StatusWhen
200A request answered, as JSON or as an event stream.
202A notification or response from the client accepted, or a session ended with DELETE.
400A malformed MCP request, such as an unsupported MCP-Protocol-Version header (Bad Request: Unsupported MCP-Protocol-Version: <version>) or a GET or DELETE without a session id (Bad Request: Session ID is required).
401No usable token: see The 401 challenge.
403Forbidden: Host header is not allowed: the Host is not PUBLIC_URL’s host, localhost, 127.0.0.1 or ::1. Forbidden: Origin header is not allowed: an Origin that is neither PUBLIC_URL’s nor in ALLOWED_ORIGINS. Both protect against DNS rebinding and cross-site requests; see TLS and deployment.
404The Mcp-Session-Id names a session that does not exist, has ended, or was opened with another credential (Session not found, or rmcp’s Not Found: Session not found). The client starts a new session. On the 2026-07-28 revision, rmcp also answers 404 for a JSON-RPC method the server does not have.
405Any method other than POST, GET and DELETE, or a GET or DELETE on the 2026-07-28 revision.
406The Accept header lacks application/json or text/event-stream on a POST, or text/event-stream on a GET.
413The Content-Length declares a body over 1 MiB (length limit exceeded). A longer body sent without a declared length is cut off at the limit and answered 500 (Failed to read request body: length limit exceeded); see Body limits.
415A POST whose Content-Type is not application/json, or whose body is not JSON.
422On a protocol version before 2026-07-28, a POST without a session id that is not initialize (Unexpected message, expect initialize request).
429Too many failed attempts from this address, with Retry-After: 30: Too many attempts from this address: credentials or tokens were rejected, or several are being checked at once. Try again shortly.
503With Retry-After: 30: the person’s credential could not be checked (Your <label> could not be checked right now: <why>), the server is refusing new addresses under heavy load, or the path holds too many sessions (This server has too many open sessions. Try again shortly.).

The bearer check runs first, so a request without a usable token gets 401 whatever its Host. The Host and Origin checks apply to the MCP endpoints only. The limits behind 429, 503 and the session table are on Limits and abuse protection.

Metadata documents

Both documents are public JSON, served with 200.

Protected-resource metadata

GET /.well-known/oauth-protected-resource/<service>, for each enabled service and for mcp while the combined endpoint is on:

{
  "resource": "https://mcp.example.com/weather",
  "authorization_servers": ["https://mcp.example.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["weather"]
}
FieldValue
resourcePUBLIC_URL/<service>: the value clients send as resource, and the audience of its access tokens.
authorization_serversPUBLIC_URL, the only authorization server.
bearer_methods_supportedheader: tokens go in the Authorization header only.
scopes_supportedThe service’s name.

Any other name, and /.well-known/oauth-protected-resource itself, answers 404.

Authorization-server metadata

GET /.well-known/oauth-authorization-server:

{
  "issuer": "https://mcp.example.com",
  "authorization_endpoint": "https://mcp.example.com/authorize",
  "token_endpoint": "https://mcp.example.com/token",
  "registration_endpoint": "https://mcp.example.com/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "authorization_response_iss_parameter_supported": true,
  "scopes_supported": ["weather", "tides", "mcp"]
}
FieldValue
issuerPUBLIC_URL. Every token’s iss, and the iss parameter on authorization responses.
authorization_endpointPUBLIC_URL/authorize
token_endpointPUBLIC_URL/token
registration_endpointPUBLIC_URL/register
response_types_supportedcode
grant_types_supportedauthorization_code and refresh_token
code_challenge_methods_supportedS256
token_endpoint_auth_methods_supportednone: public clients, without a secret.
authorization_response_iss_parameter_supportedtrue (RFC 9207).
scopes_supportedThe enabled services’ names, then mcp while the combined endpoint is on.

There is no revocation, introspection or JWKS endpoint: tokens are signed with a shared secret (HS256) and verified only by servers that hold it. See What statelessness means.

OAuth endpoints

How each step works, and every error message, is on OAuth and tokens. In short:

RouteAnswers
POST /register201 with the client’s registration as JSON. 400 with invalid_client_metadata or invalid_redirect_uri for input outside the registration caps.
GET /authorize200 with the sign-in page. 400 with an error page for an unknown client or redirect URI. 302 to the redirect URI with error for other invalid requests.
POST /authorizeWith an upstream provider, 303 to the provider with a pending sign-in cookie. Otherwise 303 to the redirect URI with code, state and iss on success, or with error for an invalid request. 400 with an error page for an unknown client or redirect URI, or when the form expired or was altered. 401 with the page again for input that is not plausible or a rejected credential. 429 or 503 when the sign-in limits refuse the address, and 503 when the credential could not be checked. See The sign-in page.
GET /callback303 to the redirect URI with code, state and iss, or with error=access_denied when the person declined at the provider. 400 with an error page when the sign-in expired or was started in another browser, 401 when the provider refused the code, 503 when it could not be reached, 429 when the sign-in limits refuse the address.
POST /token200 with tokens as JSON. 400 with an OAuth error as JSON. 413 for a body over the limit. See The token endpoint.

/register reads JSON; /token and POST /authorize read forms (application/x-www-form-urlencoded).

Health and icon

GET /healthz answers 200 with the body ok, without authentication. It shows the process is serving, nothing more: it does not contact upstream services. The binary’s --healthcheck flag requests it on 127.0.0.1 at the BIND_ADDR port; see TLS and deployment.

GET /favicon.ico answers 200 with the 128x128 PNG given to Server::icon, as image/png. Without an icon the route does not exist.

Security headers

HeaderValueSent on
X-Content-Type-OptionsnosniffEvery response, including refusals such as 413 and routes added with Server::wrap_router.
Strict-Transport-Securitymax-age=31536000Every response, when the server serves certificate files (TLS_CERT_PATH and TLS_KEY_PATH). Not with a self-signed certificate or plain HTTP; see TLS and deployment.
X-Frame-OptionsDENYPages from /authorize.
Content-Security-Policydefault-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'Pages from /authorize.
Referrer-Policyno-referrerPages from /authorize.
Cache-Controlno-storePages from /authorize, the redirect after a successful sign-in and every JSON answer from /token.
Retry-After30Every 429 and 503 this crate sends: from the bearer guard, the sign-in page and the session table.

Why the sign-in page sends its headers is explained under Page headers. If you build the application with server::build_app instead of app::Server, it sends nosniff but never Strict-Transport-Security; see Lower-level API.