Let a token verifier gate the server without AuthSettings

`MCPServer(token_verifier=...)` no longer needs `auth=AuthSettings(...)`.
On its own a verifier is now a plain bearer gate: requests without a
token it accepts get a 401 whose `WWW-Authenticate` carries no
`resource_metadata`, no protected-resource metadata route is published,
and `get_access_token()` works as before. `AuthSettings` keeps its job of
describing that gate to OAuth clients (required scopes, RFC 9728
metadata, the discovery pointer in the 401), so it is what you add when
a real authorization server issues the tokens.

Previously the constructor refused a verifier without settings, which
forced anyone with a pre-shared token to invent an issuer URL, and the
low-level `Server.streamable_http_app(token_verifier=...)` accepted the
same shape but answered every request 401, valid token included, because
the authentication backend was only installed when settings were given.
Both wiring sites (and `MCPServer.sse_app`) now install the backend
whenever a verifier is present.

The authorization docs gain a "Just a pre-shared token" section with a
runnable example, and the constructor still refuses the two shapes that
cannot work: settings with nothing to gate with, and an embedded
authorization-server provider without settings for its issuer.

Author: maxisbey

docs/run/authorization.md

@@ -1,6 +1,6 @@
 # Authorization
 
-Over Streamable HTTP your MCP server is an ordinary web service, and you protect it the way you protect any web service: with OAuth 2.1 bearer tokens.
+Over Streamable HTTP your MCP server is an ordinary web service, and you protect it the way you protect any web service: with bearer tokens. Most of this page is the OAuth 2.1 shape, where an authorization server issues them; **[Just a pre-shared token](#just-a-pre-shared-token)** at the end is the smaller case where you hand one out yourself.
 
 In OAuth terms, your server is a **resource server**. It never signs anyone in and it never issues a token. It does one thing: look at the `Authorization` header on each request and decide whether the token in it is good.
 
@@ -24,7 +24,7 @@ The SDK has no opinion about what a valid token looks like. You tell it, by impl
 
 * `TokenVerifier` is a protocol with one async method. `verify_token` gets the raw token from the `Authorization` header and returns an **`AccessToken`** if it's valid, `None` if it isn't. There is nothing else to implement.
 * This one looks the token up in a table. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint. That code is yours; the SDK only calls it.
-* `token_verifier=` and `auth=` always travel together. Pass one without the other and `MCPServer(...)` raises a `ValueError` before it ever serves a request.
+* `token_verifier=` is the gate. `auth=` is what the server *publishes* about that gate, plus the scopes it insists on, so it is meaningless alone: pass `auth=` without a verifier and `MCPServer(...)` raises a `ValueError` before it ever serves a request. The reverse, a verifier with no `auth=`, is legitimate and smaller: **[Just a pre-shared token](#just-a-pre-shared-token)**.
 
 `AuthSettings` is the public face of your resource server:
 
@@ -113,12 +113,37 @@ To watch all three parties move, run `examples/servers/simple-auth/` from the SD
 
 An authorization server can also accept an enterprise identity provider's signed assertion in place of a user clicking through a consent screen, and the SDK supports both sides of that exchange. The grant, and the client that presents it, is **[Identity assertion](../client/identity-assertion.md)**.
 
+## Just a pre-shared token
+
+Sometimes there is no authorization server anywhere: you minted a token yourself, handed it to the one client that needs it, and all the server has to do is check it. Keep the verifier and drop `auth=`:
+
+```python title="server.py" hl_lines="8 13-15 18"
+--8<-- "docs_src/authorization/tutorial003.py"
+```
+
+* No `AuthSettings` means nothing is advertised. The app has the one `/mcp` route and no `/.well-known/oauth-protected-resource/mcp`, and the 401 loses its `resource_metadata` pointer. The gate itself is the same, and so is `get_access_token()`.
+* With nothing to discover, the client must arrive already holding the token. For the python `Client` that is an `Authorization` header on the `httpx2.AsyncClient` you hand to `streamable_http_client` (**[Client transports](../client/transports.md#bring-your-own-httpx2asyncclient)** has it); for a host, it is wherever that host's server entry takes request headers, usually a `headers` block. An OAuth-capable client that turns up without the token gets the 401 and has nowhere to go from there.
+* A pre-shared token is a password. Compare it with `secrets.compare_digest`, keep it in the environment and out of the source (unset, this server mints a random one at startup, so a missing variable locks the door rather than opening it), and put TLS in front of anything that is not localhost.
+
+!!! check
+    Call `/mcp` with no token and the door is exactly as shut:
+
+    ```text
+    HTTP/1.1 401 Unauthorized
+    WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required"
+
+    {"error": "invalid_token", "error_description": "Authentication required"}
+    ```
+
+    The same refusal as before, minus the `resource_metadata` that would have sent a client looking
+    for an authorization server you don't have.
+
 ## Recap
 
 * Over Streamable HTTP your server is an OAuth 2.1 **resource server**: it verifies tokens, it never issues them.
 * `TokenVerifier` is the whole integration surface: one async method, token in, `AccessToken | None` out.
-* `token_verifier=` and `auth=AuthSettings(issuer_url=..., resource_server_url=..., required_scopes=[...])` always travel together.
-* The SDK publishes [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource Metadata at `/.well-known/oauth-protected-resource/...` and answers unauthenticated requests with a 401 whose `WWW-Authenticate` header points at it. That is the entire discovery story.
+* `token_verifier=` alone is a complete gate, and the right one for a token you hand out yourself. Add `auth=AuthSettings(issuer_url=..., resource_server_url=..., required_scopes=[...])` when a real authorization server issues the tokens.
+* With `AuthSettings`, the SDK publishes [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource Metadata at `/.well-known/oauth-protected-resource/...` and answers unauthenticated requests with a 401 whose `WWW-Authenticate` header points at it. That is the entire discovery story.
 * `get_access_token()` in any handler is who's calling.
 * Authorization is an HTTP concern. `stdio` and the in-memory client never see it.
 

docs_src/authorization/tutorial003.py

@@ -0,0 +1,27 @@
+import os
+import secrets
+
+from mcp.server import MCPServer
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+API_TOKEN = os.environ.get("NOTES_API_TOKEN") or secrets.token_urlsafe(32)
+
+
+class PresharedTokenVerifier(TokenVerifier):
+    async def verify_token(self, token: str) -> AccessToken | None:
+        if secrets.compare_digest(token.encode(), API_TOKEN.encode()):
+            return AccessToken(token=token, client_id="notes-client", scopes=[])
+        return None
+
+
+mcp = MCPServer("Notes", token_verifier=PresharedTokenVerifier())
+
+
+@mcp.tool()
+def whoami() -> str:
+    """Report which client is calling."""
+    token = get_access_token()
+    if token is None:
+        return "anonymous"
+    return token.client_id

src/mcp/server/lowlevel/server.py

@@ -734,7 +734,18 @@ def streamable_http_app(
         custom_starlette_routes: list[Route] | None = None,
         debug: bool = False,
     ) -> Starlette:
-        """Return an instance of the StreamableHTTP server app."""
+        """Return an instance of the StreamableHTTP server app.
+
+        `token_verifier` is the bearer gate: with one, every request to the MCP
+        endpoint must carry an `Authorization: Bearer` token the verifier
+        accepts, and anything else is answered 401. `auth` describes that gate
+        to clients: its `required_scopes` are enforced, and when
+        `resource_server_url` is set the app serves RFC 9728 protected-resource
+        metadata and points the 401 challenge at it. Without a verifier nothing
+        is gated. `auth_server_provider` (with `auth`) additionally mounts the
+        SDK's authorization-server routes, advertised with `auth.issuer_url`
+        as the issuer.
+        """
         # Auto-enable DNS rebinding protection for localhost (IPv4 and IPv6)
         if transport_security is None and host in ("127.0.0.1", "localhost", "::1"):
             transport_security = TransportSecuritySettings(
@@ -760,57 +771,41 @@ def streamable_http_app(
         # Create routes
         routes: list[Route | Mount] = []
         middleware: list[Middleware] = []
-        required_scopes: list[str] = []
-
-        # Set up auth if configured
-        if auth:
-            required_scopes = auth.required_scopes or []
-
-            # Add auth middleware if token verifier is available
-            if token_verifier:
-                middleware = [
-                    Middleware(
-                        AuthenticationMiddleware,
-                        backend=BearerAuthBackend(token_verifier),
-                    ),
-                    Middleware(AuthContextMiddleware),
-                ]
-
-            # Add auth endpoints if auth server provider is configured
-            if auth_server_provider:
-                routes.extend(
-                    create_auth_routes(
-                        provider=auth_server_provider,
-                        issuer_url=auth.issuer_url,
-                        service_documentation_url=auth.service_documentation_url,
-                        client_registration_options=auth.client_registration_options,
-                        revocation_options=auth.revocation_options,
-                        identity_assertion_enabled=auth.identity_assertion_enabled,
-                    )
+
+        # Embedded authorization server (the legacy all-in-one shape)
+        if auth and auth_server_provider:
+            routes.extend(
+                create_auth_routes(
+                    provider=auth_server_provider,
+                    issuer_url=auth.issuer_url,
+                    service_documentation_url=auth.service_documentation_url,
+                    client_registration_options=auth.client_registration_options,
+                    revocation_options=auth.revocation_options,
+                    identity_assertion_enabled=auth.identity_assertion_enabled,
                 )
+            )
 
-        # Set up routes with or without auth
+        # A token verifier is the bearer gate: authenticate every request and
+        # refuse the MCP endpoint to anything the verifier does not accept.
+        # `auth` only adds to that: required scopes, and the RFC 9728 metadata
+        # URL the 401 challenge points at.
         if token_verifier:
-            # Determine resource metadata URL
+            middleware = [
+                Middleware(AuthenticationMiddleware, backend=BearerAuthBackend(token_verifier)),
+                Middleware(AuthContextMiddleware),
+            ]
+            required_scopes = (auth.required_scopes if auth else None) or []
             resource_metadata_url = None
-            if auth and auth.resource_server_url:  # pragma: no branch
-                # Build compliant metadata URL for WWW-Authenticate header
+            if auth and auth.resource_server_url:
                 resource_metadata_url = build_resource_metadata_url(auth.resource_server_url)
-
             routes.append(
                 Route(
                     streamable_http_path,
                     endpoint=RequireAuthMiddleware(streamable_http_app, required_scopes, resource_metadata_url),
                 )
             )
         else:
-            # Auth is disabled, no wrapper needed
-            routes.append(
-                Route(
-                    streamable_http_path,
-                    endpoint=streamable_http_app,
-                )
-            )
+            routes.append(Route(streamable_http_path, endpoint=streamable_http_app))
 
         # Add protected resource metadata endpoint if configured as RS
         if auth and auth.resource_server_url:

src/mcp/server/mcpserver/server.py

@@ -57,6 +57,7 @@
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend, RequireAuthMiddleware
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider, ProviderTokenVerifier, TokenVerifier
+from mcp.server.auth.routes import build_resource_metadata_url, create_auth_routes, create_protected_resource_routes
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.caching import CacheableMethod, CacheHint
 from mcp.server.context import HandlerResult, ServerMiddleware, ServerRequestContext
@@ -232,14 +233,16 @@ def __init__(
         # User middleware runs inside the SDK's built-ins (OpenTelemetry, then the
         # request-state boundary), outermost-first in the order given.
         self._lowlevel_server.middleware.extend(middleware or ())
-        # Validate auth configuration
+        # Validate auth configuration. A token_verifier on its own is a plain
+        # bearer gate; `auth` is what publishes metadata about it, so it needs
+        # something to gate with, and an embedded AS needs `auth` for its issuer.
         if self.settings.auth is not None:
-            if auth_server_provider and token_verifier:  # pragma: no cover
+            if auth_server_provider and token_verifier:
                 raise ValueError("Cannot specify both auth_server_provider and token_verifier")
-            if not auth_server_provider and not token_verifier:  # pragma: no cover
-                raise ValueError("Must specify either auth_server_provider or token_verifier when auth is enabled")
-        elif auth_server_provider or token_verifier:
-            raise ValueError("Cannot specify auth_server_provider or token_verifier without auth settings")
+            if not auth_server_provider and not token_verifier:
+                raise ValueError("Must specify either auth_server_provider or token_verifier with auth settings")
+        elif auth_server_provider:
+            raise ValueError("Cannot specify auth_server_provider without auth settings")
 
         self._auth_server_provider = auth_server_provider
         self._token_verifier = token_verifier
@@ -1121,45 +1124,30 @@ async def handle_sse(scope: Scope, receive: Receive, send: Send):  # pragma: no
         middleware: list[Middleware] = []
         required_scopes: list[str] = []
 
-        # Set up auth if configured
-        if self.settings.auth:  # pragma: no cover
-            required_scopes = self.settings.auth.required_scopes or []
-
-            # Add auth middleware if token verifier is available
-            if self._token_verifier:
-                middleware = [
-                    # extract auth info from request (but do not require it)
-                    Middleware(
-                        AuthenticationMiddleware,
-                        backend=BearerAuthBackend(self._token_verifier),
-                    ),
-                    # Add the auth context middleware to store
-                    # authenticated user in a contextvar
-                    Middleware(AuthContextMiddleware),
-                ]
-
-            # Add auth endpoints if auth server provider is configured
-            if self._auth_server_provider:
-                from mcp.server.auth.routes import create_auth_routes
-
-                routes.extend(
-                    create_auth_routes(
-                        provider=self._auth_server_provider,
-                        issuer_url=self.settings.auth.issuer_url,
-                        service_documentation_url=self.settings.auth.service_documentation_url,
-                        client_registration_options=self.settings.auth.client_registration_options,
-                        revocation_options=self.settings.auth.revocation_options,
-                        identity_assertion_enabled=self.settings.auth.identity_assertion_enabled,
-                    )
+        # Add auth endpoints if auth server provider is configured
+        if self.settings.auth and self._auth_server_provider:  # pragma: no cover
+            routes.extend(
+                create_auth_routes(
+                    provider=self._auth_server_provider,
+                    issuer_url=self.settings.auth.issuer_url,
+                    service_documentation_url=self.settings.auth.service_documentation_url,
+                    client_registration_options=self.settings.auth.client_registration_options,
+                    revocation_options=self.settings.auth.revocation_options,
+                    identity_assertion_enabled=self.settings.auth.identity_assertion_enabled,
                 )
+            )
 
-        # When auth is configured, require authentication
-        if self._token_verifier:  # pragma: no cover
+        # A token verifier is the bearer gate (see Server.streamable_http_app)
+        if self._token_verifier:
+            middleware = [
+                Middleware(AuthenticationMiddleware, backend=BearerAuthBackend(self._token_verifier)),
+                Middleware(AuthContextMiddleware),
+            ]
+            if self.settings.auth:
+                required_scopes = self.settings.auth.required_scopes or []
             # Determine resource metadata URL
             resource_metadata_url = None
             if self.settings.auth and self.settings.auth.resource_server_url:
-                from mcp.server.auth.routes import build_resource_metadata_url
-
                 # Build compliant metadata URL for WWW-Authenticate header
                 resource_metadata_url = build_resource_metadata_url(self.settings.auth.resource_server_url)
 
@@ -1198,9 +1186,7 @@ async def sse_endpoint(request: Request) -> Response:  # pragma: no cover
                 )
             )
         # Add protected resource metadata endpoint if configured as RS
-        if self.settings.auth and self.settings.auth.resource_server_url:  # pragma: no cover
-            from mcp.server.auth.routes import create_protected_resource_routes
-
+        if self.settings.auth and self.settings.auth.resource_server_url:
             routes.extend(
                 create_protected_resource_routes(
                     resource_url=self.settings.auth.resource_server_url,