# bearer-auth

Resource-server-only bearer auth. Pass a `TokenVerifier` + `AuthSettings`
(issuer, resource URL, required scopes) when building the streamable-HTTP app
and the SDK wires three things automatically: a bearer gate that answers 401 +
`WWW-Authenticate: Bearer ... resource_metadata=...` (or 403 `insufficient_scope`),
the RFC 9728 protected-resource-metadata document at
`/.well-known/oauth-protected-resource/mcp`, and the verified `AccessToken`
inside tool handlers via `get_access_token()`. The verifier here accepts one
static token — replace it with JWT verification or RFC 7662 introspection. No
authorization server; see `../oauth/` for the full grant flow.

## Run it

```bash
# HTTP — the client self-hosts the bearer-gated app, connects with the demo
# bearer token, then tears it down. Self-hosting uses this story's fixed :8000
# (the issuer/PRM metadata pin it), so :8000 must be free.
uv run python -m stories.bearer_auth.client --http
# same, against the lowlevel-API server variant
uv run python -m stories.bearer_auth.client --http --server server_lowlevel

# against a server you run yourself (real uvicorn on :8000). The next section's
# curl probes use it too and `kill` it when done. While it is up it owns :8000,
# so the two self-host lines above refuse to run rather than test it by mistake.
uv run python -m stories.bearer_auth.server --port 8000 &
SERVER_PID=$!
uv run python -m stories.bearer_auth.client --http http://127.0.0.1:8000/mcp
```

`Client(url)` has no `auth=` passthrough, so a target built from a bare URL
can't carry the token. Both runners close that gap the same way: `run_client`
(above) and the pytest harness thread the module's `build_auth` export onto the
`httpx.AsyncClient` underneath the transport and hand `main` a target that is
already routed through it.

## Try it without the SDK client

```bash
# no token → 401 + WWW-Authenticate pointing at the PRM document
curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# the RFC 9728 protected-resource-metadata document
curl -s http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp | jq

# done with the server you started in "Run it"
kill "$SERVER_PID"
```

## What to look at

- `client.py` `main` — opens with `async with Client(target, mode=mode) as
  client:` and that is the whole program. The `target` it receives is a
  transport that already carries the bearer token; nothing in the body knows
  auth exists.
- `client.py` `build_auth` / `StaticBearerAuth` — bearer auth client-side is
  five lines of `httpx.Auth`. `Client(url, auth=...)` is the ergonomic the SDK
  is missing; until it lands, the auth has to be threaded onto the
  `httpx.AsyncClient` underneath the transport, outside `main`.
- `server.py` — `MCPServer(token_verifier=..., auth=AuthSettings(...))` is the
  whole recipe; `streamable_http_app()` reads those constructor kwargs and
  mounts the bearer gate + PRM route.
- `server_lowlevel.py` — same gate, but `lowlevel.Server` takes
  `auth=` / `token_verifier=` at **`streamable_http_app(...)` time**, not in the
  constructor. `mcp.server.auth.*` imports are allowed in lowlevel files
  (helper-tier).
- `whoami()` — `get_access_token()` returns the per-HTTP-request `AccessToken`.
  It is **not** on `Context` (unlike other SDKs' `ctx.authInfo`); a later
  release will namespace it as `ctx.transport.auth`.

## Caveats

- `transport_security=NO_DNS_REBIND` — DNS-rebinding protection is on by default
  for localhost binds; the harness disables it because the in-process httpx
  client sends no `Origin` header. Drop the kwarg for a real deployment.
- `RESOURCE_URL` is hard-coded to port 8000 (the harness's in-process origin).
  If you change `--port`, edit `RESOURCE_URL` to match or the PRM document's
  `resource` field will be wrong.
- Auth is HTTP-only; over stdio or the in-memory transport `get_access_token()`
  returns `None` and there is no gate.
- The 401/403 status codes and `WWW-Authenticate` header are HTTP-level and
  `Client` cannot observe them; they are pinned by
  `tests/interaction/auth/test_bearer.py` and shown via `curl` above.

## Spec

[Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
· RFC 9728 (Protected Resource Metadata) · RFC 6750 (`WWW-Authenticate: Bearer`)

## See also

`oauth/` (full authorization-code grant with an in-process AS) ·
`oauth_client_credentials/` (M2M `client_credentials` grant) ·
`stateless_legacy/` (the un-gated hosting baseline).