# The HTTP transport's bearer token is not MCP authorization ## The issue `hhstream-mcp serve --http` requires `Authorization: Bearer ` on every request, where the token is a static secret an operator minted with `hhstream-mcp token mint` and pasted into a client's configuration. That is not what the Model Context Protocol says authorization is. The specification's authorization profile is **OAuth 2.1 plus RFC 9728 protected-resource metadata**. A compliant server answers an unauthenticated request with a `401` whose `WWW-Authenticate` carries a `resource_metadata` parameter pointing at `/.well-known/oauth-protected-resource`; the client fetches that, learns which authorization server to talk to, discovers *its* metadata, and runs a real flow with scopes, refresh and revocation. The MCP Python SDK ships the machinery for this — `mcp.server.auth`, its `TokenVerifier` protocol, `AuthSettings` with an `issuer_url` and a `resource_server_url`, and `RequireAuthMiddleware`. What ships here is `hhstream_mcp.http.BearerAuth`, forty lines of ASGI middleware that looks the token up in a file. The `401` carries `WWW-Authenticate: Bearer realm="hhstream"` and nothing else, because there is no authorization server to point at and advertising a metadata endpoint that does not exist would be worse than advertising nothing. The measured consequences, in order of how soon they are met: 1. **A client that only knows how to discover an authorization server cannot connect.** It will read the `401`, find no `resource_metadata`, and have nowhere to go. A client that lets a human set a header connects immediately — which is most of them today, and is why this is usable at all. 2. **There is no rotation and no expiry negotiation.** `token mint --expires-in` sets a fixed lifetime at mint time and nothing can extend it; a client that wants to keep working past it needs a human to mint another one. There is no refresh token because there is no token endpoint. 3. **There are no scopes in the protocol's sense.** A token carries `toolsets`, which is this project's own notion and invisible to a client: nothing in the handshake tells a caller what its token may do, so an agent discovers its own limits by being refused. (`AccessToken.scopes` is where these would go if the SDK's path were taken, and the SDK's middleware is what would then enforce them.) 4. **Audience is unchecked.** RFC 8707 resource indicators exist so a token minted for one server cannot be replayed at another. These tokens name no audience, so a token is as good as the operator's care in handing it out. ## Ideas 1. **Keep it, and say so.** *(what ships, and the recommended route for now)* The threat this transport actually faces is "someone on the LAN finds the port", and a 256-bit token in a header answers it. OAuth would add an authorization server to deploy, a metadata document to serve and a flow to get right, in exchange for no additional protection against that threat on a single-operator machine. The honest version of this option is the one taken: a limit written down, not a capability implied. 2. **Implement the SDK's `TokenVerifier` over the same table.** The protocol is one method (`async verify_token(token) -> AccessToken | None`) and the store already satisfies it in all but name — `Store.verify` returns a `Grant` and an `AccessToken` is a `Grant` with `client_id` and `scopes` spelled differently. That alone buys spec-shaped *verification* and lets `toolsets` become real `scopes`, enforced by the SDK's middleware rather than by `offered_for`. It does **not** buy discovery: without an issuer there is still no metadata to advertise. *(recommended as the next step, if one is wanted — it is small, and it is the half that pays.)* 3. **Serve the metadata documents and be a resource server for real.** Mint tokens as signed JWTs with an audience and an expiry, serve `/.well-known/oauth-protected-resource`, and accept an external authorization server's tokens as well as locally minted ones. This is the complete answer and is a feature in its own right, worth doing when a client that needs it actually appears. 4. **Drop the HTTP transport and tunnel stdio over SSH instead.** Rejected, but worth recording as the thing this competes with: `ssh host hhstream-mcp` is genuinely more secure — real keys, real TLS-grade transport, and no new listener — and for one operator with one machine it is the better answer. The HTTP transport exists for the client that cannot spawn a process over SSH, which is most hosted ones. ## Why it matters Medium, and the severity is about *interoperability* rather than about safety. Nothing here is weaker than it claims to be: the token is 256 bits, the refusal leaks nothing, revocation is immediate, and loopback is the default. What is missing is the part that lets an arbitrary MCP client connect without a human pasting a header — so the cost is paid in which clients work, not in how exposed the desktop is. It would move to high the moment this server is meant to be reached by a client somebody else configured, because at that point "set this header" stops being an instruction anyone can follow.