Reject non-HTTPS, non-loopback redirect URIs at client registration

Two fixes to the optional bundled OAuth authorization server (the
`auth_server_provider=` path).

The registration endpoint accepted any well-formed URL as a
`redirect_uris` entry: cleartext `http://` on a non-loopback host,
`javascript:`, `data:`, and URIs carrying a fragment all registered
successfully. The MCP authorization specification's Communication
Security section requires every redirect URI to be either localhost or
HTTPS, and OAuth 2.1 section 2.3 forbids a fragment component. Such an
entry is now rejected with `400 invalid_client_metadata`. Loopback is
exactly the three forms OAuth 2.1 section 8.4.2 names (`localhost`,
`127.0.0.1`, `[::1]`), on any port; query strings remain permitted.
This also rejects RFC 8252 private-use schemes such as
`com.example.app:/callback`: MCP restricts redirect URIs to HTTPS or
loopback, with no carve-out for native apps.

The rule lives on the request model: `RegistrationRequest`, until now a
dead alias of `OAuthClientMetadata`, becomes a real subclass with a
`redirect_uris` field validator, so a forbidden URI fails parsing and
takes the handler's existing `invalid_client_metadata` arm rather than
needing a post-parse check. `OAuthClientMetadata` itself is unchanged:
the client also serializes it when registering against third-party
authorization servers whose redirect-URI policies the SDK does not own.
The loopback host set moves to a single `LOOPBACK_HOSTS` constant in
`mcp.server.auth.provider`, shared with `validate_issuer_url`, which
previously inlined the same tuple.

Separately, the token endpoint now answers an authorization-code
exchange whose `redirect_uri` does not match the one used at
`/authorize` with `error=invalid_grant` instead of `invalid_request`.
RFC 6749 section 5.2 assigns this case to `invalid_grant` ("does not
match the redirection URI used in the authorization request"), and the
handler's other authorization-code failures already use it. The
exchange was already rejected with HTTP 400; only the `error` field
changes.

Update the affected tests and the interaction-requirement entries, and
add a migration note.

Closes #2629

Author: maxisbey

docs/migration.md

@@ -1420,6 +1420,14 @@ Leaving `resource_server_url=None` continues to disable the check entirely (ther
 
 `RefreshToken` gains an optional `resource` field so an `OAuthAuthorizationServerProvider` can propagate the original grant's audience binding through `exchange_refresh_token`; without it a refreshed access token would carry no audience and be rejected. `BearerAuthBackend.__init__` gains a keyword-only `resource_server_url: AnyHttpUrl | None = None`, wired automatically from `AuthSettings.enforced_audience`; `None` (the default, and what the SDK passes when `verifier_validates_audience` is set) means no audience is enforced.
 
+### Bundled authorization server: RFC-correct redirect-URI handling
+
+Two fixes to the optional bundled OAuth authorization server (the `auth_server_provider=` path).
+
+The token endpoint now answers an authorization-code exchange whose `redirect_uri` does not match the one used at `/authorize` with `error=invalid_grant` instead of `error=invalid_request`. RFC 6749 §5.2 assigns this case to `invalid_grant` ("does not match the redirection URI used in the authorization request"). The exchange was already rejected with HTTP 400; only the `error` field changes.
+
+The registration endpoint now rejects a `redirect_uris` entry that is neither HTTPS nor a loopback host (`localhost`, `127.0.0.1`, or `[::1]`) with `400 invalid_client_metadata`. Previously any well-formed URL — including cleartext `http://` on a non-loopback host, `javascript:`, and `data:` — was accepted and stored. The MCP authorization specification's Communication Security section requires every redirect URI to be either `localhost` or HTTPS; the SDK accepts the three loopback forms OAuth 2.1 §8.4.2 names. Local development against `http://localhost:*`, `http://127.0.0.1:*`, or `http://[::1]:*` is unaffected. Note that this also rejects RFC 8252 private-use URI schemes (such as `com.example.app:/callback`): MCP restricts redirect URIs to HTTPS or loopback, which is stricter than vanilla OAuth allows for native apps. A redirect URI carrying a fragment component is also rejected (OAuth 2.1 §2.3). Query strings remain permitted.
+
 ### Lowlevel `Server`: `subscribe` capability now correctly reported
 
 Previously, the lowlevel `Server` hardcoded `subscribe=False` in resource capabilities even when a `subscribe_resource()` handler was registered. The `subscribe` capability is now dynamically set to `True` when an `on_subscribe_resource` handler is provided. Clients that previously didn't see `subscribe: true` in capabilities will now see it when a handler is registered, which may change client behavior.

src/mcp/server/auth/handlers/register.py

@@ -4,19 +4,43 @@
 from typing import Any
 from uuid import uuid4
 
-from pydantic import BaseModel, ValidationError
+from pydantic import AnyUrl, BaseModel, ValidationError, field_validator
 from starlette.requests import Request
 from starlette.responses import Response
 
 from mcp.server.auth.errors import stringify_pydantic_error
 from mcp.server.auth.json_response import PydanticJSONResponse
-from mcp.server.auth.provider import OAuthAuthorizationServerProvider, RegistrationError, RegistrationErrorCode
+from mcp.server.auth.provider import (
+    LOOPBACK_HOSTS,
+    OAuthAuthorizationServerProvider,
+    RegistrationError,
+    RegistrationErrorCode,
+)
 from mcp.server.auth.settings import ClientRegistrationOptions
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata
 
-# this alias is a no-op; it's just to separate out the types exposed to the
-# provider from what we use in the HTTP handler
-RegistrationRequest = OAuthClientMetadata
+
+class RegistrationRequest(OAuthClientMetadata):
+    """The registration endpoint's inbound client metadata, with server-side redirect-URI policy.
+
+    The MCP authorization spec requires every redirect URI to use HTTPS or target a loopback
+    host, and OAuth 2.1 section 2.3 forbids a fragment component, so a request carrying a URI
+    that violates either fails validation and never reaches the provider. The base
+    `OAuthClientMetadata` stays permissive: the client also serializes it when registering
+    against third-party authorization servers whose redirect-URI policies the SDK does not own.
+    """
+
+    @field_validator("redirect_uris", mode="after")
+    @classmethod
+    def _https_or_loopback_without_fragment(cls, v: list[AnyUrl] | None) -> list[AnyUrl] | None:
+        # None and an empty list both mean there is nothing to check.
+        for uri in v or []:
+            if uri.scheme != "https" and uri.host not in LOOPBACK_HOSTS:
+                raise ValueError(f"redirect_uri must use https or target a loopback host: {uri}")
+            # `is not None`, not truthiness: a bare `https://x/cb#` parses with fragment == "".
+            if uri.fragment is not None:
+                raise ValueError(f"redirect_uri must not include a fragment: {uri}")
+        return v
 
 
 class RegistrationErrorResponse(BaseModel):
@@ -33,7 +57,7 @@ async def handle(self, request: Request) -> Response:
         # Implements dynamic client registration as defined in https://datatracker.ietf.org/doc/html/rfc7591#section-3.1
         try:
             body = await request.body()
-            client_metadata = OAuthClientMetadata.model_validate_json(body)
+            client_metadata = RegistrationRequest.model_validate_json(body)
 
             # Scope validation is handled below
         except ValidationError as validation_error:

src/mcp/server/auth/handlers/token.py

@@ -154,7 +154,7 @@ async def handle(self, request: Request):
                 if token_redirect_str != auth_redirect_str:
                     return self.response(
                         TokenErrorResponse(
-                            error="invalid_request",
+                            error="invalid_grant",
                             error_description=("redirect_uri did not match the one used when creating auth code"),
                         )
                     )

src/mcp/server/auth/provider.py

@@ -6,6 +6,10 @@
 
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
 
+# OAuth 2.1 §8.4.2: the loopback IP literal `127.0.0.1` or `[::1]`, or the hostname `localhost`.
+# Spelled as pydantic's `AnyUrl.host` reports them (an IPv6 literal keeps its brackets).
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "[::1]"})
+
 
 class AuthorizationParams(BaseModel):
     state: str | None

src/mcp/server/auth/routes.py

@@ -15,7 +15,7 @@
 from mcp.server.auth.handlers.revoke import RevocationHandler
 from mcp.server.auth.handlers.token import TokenHandler
 from mcp.server.auth.middleware.client_auth import ClientAuthenticator
-from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+from mcp.server.auth.provider import LOOPBACK_HOSTS, OAuthAuthorizationServerProvider
 from mcp.server.auth.settings import ClientRegistrationOptions, RevocationOptions
 from mcp.shared.auth import OAuthMetadata, ProtectedResourceMetadata
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
@@ -32,7 +32,7 @@ def validate_issuer_url(url: AnyHttpUrl):
     """
 
     # RFC 8414 requires HTTPS, but we allow loopback/localhost HTTP for testing
-    if url.scheme != "https" and url.host not in ("localhost", "127.0.0.1", "[::1]"):
+    if url.scheme != "https" and url.host not in LOOPBACK_HOSTS:
         raise ValueError("Issuer URL must be HTTPS")
 
     # No fragments or query parameters allowed

tests/interaction/_requirements.py

@@ -2733,28 +2733,15 @@ def __post_init__(self) -> None:
         ),
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; the bundled AS is an ASGI app.",
-        divergence=Divergence(
-            note=(
-                "RFC 6749 §5.2 assigns redirect_uri mismatch at the token endpoint to invalid_grant; "
-                "the SDK's TokenHandler returns invalid_request (src/mcp/server/auth/handlers/token.py:157). "
-                "The rejection itself is the security-relevant property and is correct."
-            ),
-        ),
     ),
     "hosting:auth:as:redirect-uri-scheme": Requirement(
         source=f"{SPEC_BASE_URL}/basic/authorization#communication-security",
         behavior=(
-            "The bundled registration endpoint accepts only redirect URIs that use HTTPS or target a loopback host."
+            "The bundled registration endpoint accepts only redirect URIs that use HTTPS or target a loopback "
+            "host (`localhost`, `127.0.0.1`, `[::1]`), and that carry no fragment component."
         ),
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; the bundled AS is an ASGI app.",
-        divergence=Divergence(
-            note=(
-                "Not enforced: the registration handler models redirect_uris as AnyUrl with no scheme or "
-                "host check, so http://evil.example/callback is accepted and registered. The spec's "
-                "localhost-or-HTTPS rule is left to the provider implementation."
-            ),
-        ),
     ),
     "hosting:auth:as:token-cache-headers": Requirement(
         source="sdk",

tests/interaction/auth/test_as_handlers.py

@@ -170,16 +170,15 @@ async def test_reusing_an_authorization_code_is_rejected_with_invalid_grant(
 
 
 @requirement("hosting:auth:as:redirect-uri-binding")
-async def test_a_redirect_uri_differing_from_authorize_is_rejected_at_the_token_endpoint(
+async def test_a_token_exchange_with_a_mismatched_redirect_uri_is_rejected_with_invalid_grant(
     as_app: tuple[httpx.AsyncClient, InMemoryAuthorizationServerProvider],
 ) -> None:
-    """A token exchange whose `redirect_uri` differs from the one used at authorize is rejected.
+    """A token exchange whose `redirect_uri` differs from the one used at authorize is rejected with `invalid_grant`.
 
     This is the security-critical half of redirect-URI binding: a code intercepted via redirect
     substitution cannot be redeemed because the attacker cannot reproduce the original authorize
-    redirect URI at the token endpoint. RFC 6749 §5.2 specifies `invalid_grant` for this case;
-    the SDK returns `invalid_request` (see the divergence on the requirement). The rejection
-    itself is the security property and is correct.
+    redirect URI at the token endpoint. RFC 6749 §5.2 assigns the mismatch to `invalid_grant`,
+    matching the handler's other authorization-code failures.
     """
     http, _ = as_app
     client_info, code, verifier = await _mint_code(http)
@@ -192,7 +191,7 @@ async def test_a_redirect_uri_differing_from_authorize_is_rejected_at_the_token_
     assert response.status_code == 400
     assert response.json() == snapshot(
         {
-            "error": "invalid_request",
+            "error": "invalid_grant",
             "error_description": "redirect_uri did not match the one used when creating auth code",
         }
     )
@@ -279,22 +278,93 @@ async def test_authorize_with_an_unregistered_redirect_uri_is_rejected_directly(
 
 
 @requirement("hosting:auth:as:redirect-uri-scheme")
-async def test_a_non_loopback_http_redirect_uri_is_accepted_at_registration(
-    as_app: tuple[httpx.AsyncClient, InMemoryAuthorizationServerProvider],
+@pytest.mark.parametrize(
+    "redirect_uri",
+    [
+        "http://evil.example/callback",
+        "http://localhost.evil.example/callback",
+        "javascript:alert(1)",
+        "com.example.app:/oauth/cb",
+    ],
+)
+async def test_a_redirect_uri_that_is_neither_https_nor_loopback_is_rejected_at_registration(
+    as_app: tuple[httpx.AsyncClient, InMemoryAuthorizationServerProvider], redirect_uri: str
+) -> None:
+    """A registration whose redirect URI is neither HTTPS nor a loopback host is rejected with 400.
+
+    The spec requires every redirect URI to be either HTTPS or a loopback host; the
+    registration request model enforces this at parse time so the provider never sees the
+    client. Loopback is matched on the whole host (`localhost.evil.example` is not loopback),
+    and a scheme with no authority — `javascript:`, or an RFC 8252 private-use scheme such as
+    `com.example.app:` — fails the same check.
+    """
+    http, provider = as_app
+    body = oauth_client_metadata().model_dump(mode="json", exclude_none=True)
+    body["redirect_uris"] = [redirect_uri]
+
+    response = await http.post("/register", json=body)
+
+    assert response.status_code == 400
+    error = response.json()
+    assert error["error"] == "invalid_client_metadata"
+    # Pydantic frames the validator's message as `redirect_uris: Value error, <msg>` (third-party
+    # text), so assert only the SDK-authored sentence to pin which validation fired.
+    assert "redirect_uri must use https or target a loopback host" in error["error_description"]
+    assert provider.clients == {}
+
+
+@requirement("hosting:auth:as:redirect-uri-scheme")
+@pytest.mark.parametrize(
+    "redirect_uri",
+    [
+        "https://app.example.com/callback",
+        "http://localhost:3030/callback",
+        "http://127.0.0.1:8000/callback",
+        "http://[::1]:8000/callback",
+    ],
+)
+async def test_an_https_or_loopback_redirect_uri_is_accepted_at_registration(
+    as_app: tuple[httpx.AsyncClient, InMemoryAuthorizationServerProvider], redirect_uri: str
 ) -> None:
-    """A registration carrying a non-HTTPS, non-loopback redirect URI is accepted.
+    """A registration whose redirect URI uses HTTPS or targets a loopback host is accepted and stored.
 
-    The spec requires every redirect URI to be either HTTPS or a loopback host; the bundled
-    registration handler does not enforce this and registers `http://evil.example/callback`
-    successfully. See the divergence on the requirement.
+    Loopback covers exactly the three forms OAuth 2.1 names: the hostname `localhost` and the
+    loopback IP literals `127.0.0.1` and `[::1]`, on any port, over plain HTTP.
     """
     http, provider = as_app
     body = oauth_client_metadata().model_dump(mode="json", exclude_none=True)
-    body["redirect_uris"] = ["http://evil.example/callback"]
+    body["redirect_uris"] = [redirect_uri]
 
     response = await http.post("/register", json=body)
 
     assert response.status_code == 201
     info = OAuthClientInformationFull.model_validate_json(response.content)
-    assert [str(u) for u in (info.redirect_uris or [])] == ["http://evil.example/callback"]
+    assert [str(u) for u in (info.redirect_uris or [])] == [redirect_uri]
     assert info.client_id in provider.clients
+
+
+@requirement("hosting:auth:as:redirect-uri-scheme")
+@pytest.mark.parametrize(
+    "redirect_uri", ["https://app.example.com/callback#", "https://app.example.com/callback#nonce"]
+)
+async def test_a_redirect_uri_carrying_a_fragment_is_rejected_at_registration(
+    as_app: tuple[httpx.AsyncClient, InMemoryAuthorizationServerProvider], redirect_uri: str
+) -> None:
+    """A registration whose redirect URI carries a fragment component is rejected with 400.
+
+    OAuth 2.1 section 2.3: a redirect URI MUST NOT include a fragment component. The bare
+    trailing `#` parses to an empty-string fragment and is rejected the same as a named one.
+    """
+    http, provider = as_app
+    body = oauth_client_metadata().model_dump(mode="json", exclude_none=True)
+    body["redirect_uris"] = [redirect_uri]
+
+    response = await http.post("/register", json=body)
+
+    assert response.status_code == 400
+    error = response.json()
+    assert error["error"] == "invalid_client_metadata"
+    # Pydantic frames the validator's message as `redirect_uris: Value error, <msg>` (third-party
+    # text), so assert only the SDK-authored sentence to pin which validation fired.
+    assert "redirect_uri must not include a fragment" in error["error_description"]
+    assert provider.clients == {}

tests/server/mcpserver/auth/test_auth_integration.py

@@ -501,7 +501,7 @@ async def test_token_redirect_uri_mismatch(
         )
         assert response.status_code == 400
         error_response = response.json()
-        assert error_response["error"] == "invalid_request"
+        assert error_response["error"] == "invalid_grant"
         assert "redirect_uri did not match" in error_response["error_description"]
 
     @pytest.mark.anyio