Fix OAuth example resource identifiers

Author: kinocode3

docs/run/authorization.md

@@ -29,7 +29,7 @@ The SDK has no opinion about what a valid token looks like. You tell it, by impl
 `AuthSettings` is the public face of your resource server:
 
 * `issuer_url`: the authorization server that issues your tokens.
-* `resource_server_url`: the public URL of this MCP endpoint. It names *which* resource a token is for, and it's where the discovery document lives.
+* `resource_server_url`: the complete public URL of this MCP endpoint, including its path (for example, `/mcp`). It names *which* resource a token is for, and it's where the discovery document lives. Use the externally visible URL when a proxy or mounted application changes the public path; the SDK does not infer it from the internal route.
 * `required_scopes`: every token must carry all of them.
 
 !!! tip

examples/clients/simple-auth-client/mcp_simple_auth_client/main.py

@@ -214,7 +214,7 @@ async def _default_redirect_handler(authorization_url: str) -> None:
             # Create OAuth authentication handler using the new interface
             # Use client_metadata_url to enable CIMD when the server supports it
             oauth_auth = OAuthClientProvider(
-                server_url=self.server_url.replace("/mcp", ""),
+                server_url=self.server_url,
                 client_metadata=OAuthClientMetadata.model_validate(client_metadata_dict),
                 storage=InMemoryTokenStorage(),
                 redirect_handler=_default_redirect_handler,

examples/servers/simple-auth/README.md

@@ -38,6 +38,26 @@ uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --tran
 
 ```
 
+The resource identifier defaults to the selected transport endpoint: `/mcp` for
+Streamable HTTP and `/sse` for SSE. If a proxy or mounted application exposes a
+different public URL, pass the complete endpoint explicitly:
+
+```bash
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 \
+  --resource-server-url=https://gateway.example.com/services/time/mcp
+```
+
+Configure the proxy to forward the corresponding public well-known path (for
+this example, `/.well-known/oauth-protected-resource/services/time/mcp`) to the
+resource-server application as well.
+
+For SSE, both the transport and protected-resource metadata use `/sse`:
+
+```bash
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=sse
+curl http://localhost:8001/.well-known/oauth-protected-resource/sse
+```
+
 ### Step 3: Test with Client
 
 ```bash
@@ -53,12 +73,12 @@ MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-c
 **Client → Resource Server:**
 
 ```bash
-curl http://localhost:8001/.well-known/oauth-protected-resource
+curl http://localhost:8001/.well-known/oauth-protected-resource/mcp
 ```
 
 ```json
 {
-  "resource": "http://localhost:8001",
+  "resource": "http://localhost:8001/mcp",
   "authorization_servers": ["http://localhost:9000"]
 }
 ```
@@ -119,7 +139,7 @@ This ensures existing MCP servers (which could optionally act as Authorization S
 
 ```bash
 # Test Resource Server discovery endpoint (new architecture)
-curl -v http://localhost:8001/.well-known/oauth-protected-resource
+curl -v http://localhost:8001/.well-known/oauth-protected-resource/mcp
 
 # Test Authorization Server metadata
 curl -v http://localhost:9000/.well-known/oauth-authorization-server

examples/servers/simple-auth/mcp_simple_auth/server.py

@@ -99,6 +99,11 @@ async def get_time() -> dict[str, Any]:
 @click.command()
 @click.option("--port", default=8001, help="Port to listen on")
 @click.option("--auth-server", default="http://localhost:9000", help="Authorization Server URL")
+@click.option(
+    "--resource-server-url",
+    envvar="MCP_RESOURCE_SERVER_URL",
+    help="Complete public MCP endpoint URL (defaults to the selected transport path)",
+)
 @click.option(
     "--transport",
     default="streamable-http",
@@ -110,7 +115,13 @@ async def get_time() -> dict[str, Any]:
     is_flag=True,
     help="Enable RFC 8707 resource validation",
 )
-def main(port: int, auth_server: str, transport: Literal["sse", "streamable-http"], oauth_strict: bool) -> int:
+def main(
+    port: int,
+    auth_server: str,
+    resource_server_url: str | None,
+    transport: Literal["sse", "streamable-http"],
+    oauth_strict: bool,
+) -> int:
     """Run the MCP Resource Server.
 
     This server:
@@ -128,7 +139,8 @@ def main(port: int, auth_server: str, transport: Literal["sse", "streamable-http
 
         # Create settings
         host = "localhost"
-        server_url = f"http://{host}:{port}/mcp"
+        transport_path = "/sse" if transport == "sse" else "/mcp"
+        server_url = resource_server_url or f"http://{host}:{port}{transport_path}"
         settings = ResourceServerSettings(
             host=host,
             port=port,
@@ -139,7 +151,7 @@ def main(port: int, auth_server: str, transport: Literal["sse", "streamable-http
         )
     except ValueError as e:
         logger.error(f"Configuration error: {e}")
-        logger.error("Make sure to provide a valid Authorization Server URL")
+        logger.error("Make sure to provide valid Authorization and Resource Server URLs")
         return 1
 
     try:
@@ -148,8 +160,16 @@ def main(port: int, auth_server: str, transport: Literal["sse", "streamable-http
         logger.info(f"🚀 MCP Resource Server running on {settings.server_url}")
         logger.info(f"🔑 Using Authorization Server: {settings.auth_server_url}")
 
-        # Run the server - this should block and keep running
-        mcp_server.run(transport=transport, host=host, port=port)
+        # Keep the advertised resource path and the listening route in lockstep.
+        if transport == "sse":
+            mcp_server.run(transport="sse", host=host, port=port, sse_path=transport_path)
+        else:
+            mcp_server.run(
+                transport="streamable-http",
+                host=host,
+                port=port,
+                streamable_http_path=transport_path,
+            )
         logger.info("Server stopped")
         return 0
     except Exception:

examples/snippets/clients/oauth_client.py

@@ -59,7 +59,7 @@ async def handle_callback() -> AuthorizationCodeResult:
 async def main():
     """Run the OAuth client example."""
     oauth_auth = OAuthClientProvider(
-        server_url="http://localhost:8001",
+        server_url="http://localhost:8001/mcp",
         client_metadata=OAuthClientMetadata(
             client_name="Example MCP Client",
             redirect_uris=[AnyUrl("http://localhost:3000/callback")],

examples/snippets/servers/oauth_server.py

@@ -24,7 +24,7 @@ async def verify_token(self, token: str) -> AccessToken | None:
     # Auth settings for RFC 9728 Protected Resource Metadata
     auth=AuthSettings(
         issuer_url=AnyHttpUrl("https://auth.example.com"),  # Authorization Server URL
-        resource_server_url=AnyHttpUrl("http://localhost:3001"),  # This server's URL
+        resource_server_url=AnyHttpUrl("http://localhost:8000/mcp"),  # This server's MCP endpoint
         required_scopes=["user"],
     ),
 )

pyproject.toml

@@ -175,6 +175,8 @@ executionEnvironments = [
     { root = "tests", extraPaths = [
         ".",
         "examples",
+        "examples/clients/simple-auth-client",
+        "examples/servers/simple-auth",
     ], reportUnusedFunction = false, reportPrivateUsage = false },
     { root = "examples/stories", extraPaths = [
         "examples",

src/mcp/server/auth/settings.py

@@ -37,6 +37,7 @@ class AuthSettings(BaseModel):
     # Resource Server settings (when operating as RS only)
     resource_server_url: AnyHttpUrl | None = Field(
         ...,
-        description="The URL of the MCP server to be used as the resource identifier "
-        "and base route to look up OAuth Protected Resource Metadata.",
+        description="The complete externally visible URL of the MCP endpoint, including "
+        "any path prefix and transport path. Used as the resource identifier and to locate "
+        "OAuth Protected Resource Metadata.",
     )

tests/examples/simple_auth/conftest.py

@@ -0,0 +1,8 @@
+import sys
+from pathlib import Path
+
+REPOSITORY_ROOT = Path(__file__).parents[3]
+sys.path[:0] = [
+    str(REPOSITORY_ROOT / "examples" / "clients" / "simple-auth-client"),
+    str(REPOSITORY_ROOT / "examples" / "servers" / "simple-auth"),
+]

tests/examples/simple_auth/test_oauth_resource_url.py

@@ -0,0 +1,44 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import pytest
+from mcp_simple_auth_client import main as client_module
+from mcp_simple_auth_client.main import SimpleAuthClient
+
+from mcp.client.auth import OAuthClientProvider
+
+pytestmark = pytest.mark.anyio
+
+
+async def test_the_oauth_provider_receives_the_complete_connection_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The client preserves path prefixes, the transport path, and the query in the resource identifier."""
+    resource_url = "https://mcp.example.com/prefix/mcp?tenant=mcp"
+    providers: list[OAuthClientProvider] = []
+    session_calls: list[tuple[Any, Any]] = []
+
+    class FakeCallbackServer:
+        def __init__(self, port: int) -> None:
+            assert port == 3030
+
+        def start(self) -> None:
+            pass
+
+    @asynccontextmanager
+    async def fake_sse_client(**kwargs: Any) -> AsyncIterator[tuple[object, object]]:
+        assert kwargs["url"] == resource_url
+        assert isinstance(kwargs["auth"], OAuthClientProvider)
+        providers.append(kwargs["auth"])
+        yield object(), object()
+
+    async def fake_run_session(self: SimpleAuthClient, read_stream: Any, write_stream: Any) -> None:
+        session_calls.append((read_stream, write_stream))
+
+    monkeypatch.setattr(client_module, "CallbackServer", FakeCallbackServer)
+    monkeypatch.setattr(client_module, "sse_client", fake_sse_client)
+    monkeypatch.setattr(SimpleAuthClient, "_run_session", fake_run_session)
+
+    await SimpleAuthClient(resource_url, transport_type="sse").connect()
+
+    assert [provider.context.server_url for provider in providers] == [resource_url]
+    assert len(session_calls) == 1