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
| Method | Path | Authentication | Purpose |
|---|---|---|---|
GET | /healthz | none | Liveness check: answers ok. |
GET | /favicon.ico | none | The server’s icon, when Server::icon is set. |
GET | /.well-known/oauth-protected-resource/<service> | none | Protected-resource metadata of one service, or of mcp (RFC 9728). |
GET | /.well-known/oauth-authorization-server | none | Authorization-server metadata (RFC 8414). |
POST | /register | none | Dynamic client registration (RFC 7591). |
GET | /authorize | none | The sign-in page. |
POST | /authorize | the credential, in the form | Signs the person in and redirects to the client with a code. |
POST | /token | a code and its PKCE verifier, or a refresh token | Issues access and refresh tokens. |
GET | /callback | the pending sign-in’s cookie and state | Only 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 token | One service’s MCP endpoint (Streamable HTTP). |
POST, GET, DELETE | /mcp | bearer token | Every 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
/mcpwhen it is turned off. A known path called with another method answers 405. - Routes you add with
Server::wrap_routerare 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 itsContent-Lengthdeclares 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:
| Method | Request | Answer |
|---|---|---|
POST | A 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. |
GET | Accept: text/event-stream and the Mcp-Session-Id header. | The session’s stream of server-sent events. |
DELETE | The 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:
| Token | Accepted when |
|---|---|
| An access token this server issued for this path | Its grant still holds; see OAuth and tokens. A token for another path is refused. |
MCP_AUTH_TOKEN | It is set. See The static token. |
| The person’s own credential | People 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
| Status | When |
|---|---|
200 | A request answered, as JSON or as an event stream. |
202 | A notification or response from the client accepted, or a session ended with DELETE. |
400 | A 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). |
401 | No usable token: see The 401 challenge. |
403 | Forbidden: 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. |
404 | The 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. |
405 | Any method other than POST, GET and DELETE, or a GET or DELETE on the 2026-07-28 revision. |
406 | The Accept header lacks application/json or text/event-stream on a POST, or text/event-stream on a GET. |
413 | The 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. |
415 | A POST whose Content-Type is not application/json, or whose body is not JSON. |
422 | On a protocol version before 2026-07-28, a POST without a session id that is not initialize (Unexpected message, expect initialize request). |
429 | Too 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. |
503 | With 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"]
}
| Field | Value |
|---|---|
resource | PUBLIC_URL/<service>: the value clients send as resource, and the audience of its access tokens. |
authorization_servers | PUBLIC_URL, the only authorization server. |
bearer_methods_supported | header: tokens go in the Authorization header only. |
scopes_supported | The 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"]
}
| Field | Value |
|---|---|
issuer | PUBLIC_URL. Every token’s iss, and the iss parameter on authorization responses. |
authorization_endpoint | PUBLIC_URL/authorize |
token_endpoint | PUBLIC_URL/token |
registration_endpoint | PUBLIC_URL/register |
response_types_supported | code |
grant_types_supported | authorization_code and refresh_token |
code_challenge_methods_supported | S256 |
token_endpoint_auth_methods_supported | none: public clients, without a secret. |
authorization_response_iss_parameter_supported | true (RFC 9207). |
scopes_supported | The 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:
| Route | Answers |
|---|---|
POST /register | 201 with the client’s registration as JSON. 400 with invalid_client_metadata or invalid_redirect_uri for input outside the registration caps. |
GET /authorize | 200 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 /authorize | With 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 /callback | 303 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 /token | 200 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
| Header | Value | Sent on |
|---|---|---|
X-Content-Type-Options | nosniff | Every response, including refusals such as 413 and routes added with Server::wrap_router. |
Strict-Transport-Security | max-age=31536000 | Every 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-Options | DENY | Pages from /authorize. |
Content-Security-Policy | default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none' | Pages from /authorize. |
Referrer-Policy | no-referrer | Pages from /authorize. |
Cache-Control | no-store | Pages from /authorize, the redirect after a successful sign-in and every JSON answer from /token. |
Retry-After | 30 | Every 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.