chore: import upstream snapshot with attribution

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

@@ -0,0 +1 @@
+"""Simple MCP server with GitHub OAuth authentication."""

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

@@ -0,0 +1,7 @@
+"""Main entry point for simple MCP server with GitHub OAuth authentication."""
+
+import sys
+
+from mcp_simple_auth.server import main
+
+sys.exit(main())  # type: ignore[call-arg]

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

@@ -0,0 +1,185 @@
+"""Authorization Server for MCP Split Demo.
+
+This server handles OAuth flows, client registration, and token issuance.
+Can be replaced with enterprise authorization servers like Auth0, Entra ID, etc.
+
+NOTE: this is a simplified example for demonstration purposes.
+This is not a production-ready implementation.
+
+"""
+
+import asyncio
+import logging
+import time
+
+import click
+from pydantic import AnyHttpUrl, BaseModel
+from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+from uvicorn import Config, Server
+
+from mcp.server.auth.routes import cors_middleware, create_auth_routes
+from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
+
+from .simple_auth_provider import SimpleAuthSettings, SimpleOAuthProvider
+
+logger = logging.getLogger(__name__)
+
+
+class AuthServerSettings(BaseModel):
+    """Settings for the Authorization Server."""
+
+    # Server settings
+    host: str = "localhost"
+    port: int = 9000
+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:9000")
+    auth_callback_path: str = "http://localhost:9000/login/callback"
+
+
+class SimpleAuthProvider(SimpleOAuthProvider):
+    """Authorization Server provider with simple demo authentication.
+
+    This provider:
+    1. Issues MCP tokens after simple credential authentication
+    2. Stores token state for introspection by Resource Servers
+    """
+
+    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str):
+        super().__init__(auth_settings, auth_callback_path, server_url)
+
+
+def create_authorization_server(server_settings: AuthServerSettings, auth_settings: SimpleAuthSettings) -> Starlette:
+    """Create the Authorization Server application."""
+    oauth_provider = SimpleAuthProvider(
+        auth_settings, server_settings.auth_callback_path, str(server_settings.server_url)
+    )
+
+    mcp_auth_settings = AuthSettings(
+        issuer_url=server_settings.server_url,
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=[auth_settings.mcp_scope],
+            default_scopes=[auth_settings.mcp_scope],
+        ),
+        required_scopes=[auth_settings.mcp_scope],
+        resource_server_url=None,
+    )
+
+    # Create OAuth routes
+    routes = create_auth_routes(
+        provider=oauth_provider,
+        issuer_url=mcp_auth_settings.issuer_url,
+        service_documentation_url=mcp_auth_settings.service_documentation_url,
+        client_registration_options=mcp_auth_settings.client_registration_options,
+        revocation_options=mcp_auth_settings.revocation_options,
+    )
+
+    # Add login page route (GET)
+    async def login_page_handler(request: Request) -> Response:
+        """Show login form."""
+        state = request.query_params.get("state")
+        if not state:
+            raise HTTPException(400, "Missing state parameter")
+        return await oauth_provider.get_login_page(state)
+
+    routes.append(Route("/login", endpoint=login_page_handler, methods=["GET"]))
+
+    # Add login callback route (POST)
+    async def login_callback_handler(request: Request) -> Response:
+        """Handle simple authentication callback."""
+        return await oauth_provider.handle_login_callback(request)
+
+    routes.append(Route("/login/callback", endpoint=login_callback_handler, methods=["POST"]))
+
+    # Add token introspection endpoint (RFC 7662) for Resource Servers
+    async def introspect_handler(request: Request) -> Response:
+        """Token introspection endpoint for Resource Servers.
+
+        Resource Servers call this endpoint to validate tokens without
+        needing direct access to token storage.
+        """
+        form = await request.form()
+        token = form.get("token")
+        if not token or not isinstance(token, str):
+            return JSONResponse({"active": False}, status_code=400)
+
+        # Look up token in provider
+        access_token = await oauth_provider.load_access_token(token)
+        if not access_token:
+            return JSONResponse({"active": False})
+
+        return JSONResponse(
+            {
+                "active": True,
+                "client_id": access_token.client_id,
+                "scope": " ".join(access_token.scopes),
+                "exp": access_token.expires_at,
+                "iat": int(time.time()),
+                "token_type": "Bearer",
+                "aud": access_token.resource,  # RFC 8707 audience claim
+                "sub": access_token.subject,  # RFC 7662 subject
+                "iss": str(server_settings.server_url),
+            }
+        )
+
+    routes.append(
+        Route(
+            "/introspect",
+            endpoint=cors_middleware(introspect_handler, ["POST", "OPTIONS"]),
+            methods=["POST", "OPTIONS"],
+        )
+    )
+
+    return Starlette(routes=routes)
+
+
+async def run_server(server_settings: AuthServerSettings, auth_settings: SimpleAuthSettings):
+    """Run the Authorization Server."""
+    auth_server = create_authorization_server(server_settings, auth_settings)
+
+    config = Config(
+        auth_server,
+        host=server_settings.host,
+        port=server_settings.port,
+        log_level="info",
+    )
+    server = Server(config)
+
+    logger.info(f"🚀 MCP Authorization Server running on {server_settings.server_url}")
+
+    await server.serve()
+
+
+@click.command()
+@click.option("--port", default=9000, help="Port to listen on")
+def main(port: int) -> int:
+    """Run the MCP Authorization Server.
+
+    This server handles OAuth flows and can be used by multiple Resource Servers.
+
+    Uses simple hardcoded credentials for demo purposes.
+    """
+    logging.basicConfig(level=logging.INFO)
+
+    # Load simple auth settings
+    auth_settings = SimpleAuthSettings()
+
+    # Create server settings
+    host = "localhost"
+    server_url = f"http://{host}:{port}"
+    server_settings = AuthServerSettings(
+        host=host,
+        port=port,
+        server_url=AnyHttpUrl(server_url),
+        auth_callback_path=f"{server_url}/login",
+    )
+
+    asyncio.run(run_server(server_settings, auth_settings))
+    return 0
+
+
+if __name__ == "__main__":
+    main()  # type: ignore[call-arg]

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

@@ -0,0 +1,137 @@
+"""Legacy Combined Authorization Server + Resource Server for MCP.
+
+This server implements the old spec where MCP servers could act as both AS and RS.
+Used for backwards compatibility testing with the new split AS/RS architecture.
+
+NOTE: this is a simplified example for demonstration purposes.
+This is not a production-ready implementation.
+
+"""
+
+import datetime
+import logging
+from typing import Any, Literal
+
+import click
+from pydantic import AnyHttpUrl, BaseModel
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import Response
+
+from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
+from mcp.server.mcpserver.server import MCPServer
+
+from .simple_auth_provider import SimpleAuthSettings, SimpleOAuthProvider
+
+logger = logging.getLogger(__name__)
+
+
+class ServerSettings(BaseModel):
+    """Settings for the simple auth MCP server."""
+
+    # Server settings
+    host: str = "localhost"
+    port: int = 8000
+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8000")
+    auth_callback_path: str = "http://localhost:8000/login/callback"
+
+
+class LegacySimpleOAuthProvider(SimpleOAuthProvider):
+    """Simple OAuth provider for legacy MCP server."""
+
+    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str):
+        super().__init__(auth_settings, auth_callback_path, server_url)
+
+
+def create_simple_mcp_server(server_settings: ServerSettings, auth_settings: SimpleAuthSettings) -> MCPServer:
+    """Create a simple MCPServer server with simple authentication."""
+    oauth_provider = LegacySimpleOAuthProvider(
+        auth_settings, server_settings.auth_callback_path, str(server_settings.server_url)
+    )
+
+    mcp_auth_settings = AuthSettings(
+        issuer_url=server_settings.server_url,
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=[auth_settings.mcp_scope],
+            default_scopes=[auth_settings.mcp_scope],
+        ),
+        required_scopes=[auth_settings.mcp_scope],
+        # No resource_server_url parameter in legacy mode
+        resource_server_url=None,
+    )
+
+    app = MCPServer(
+        name="Simple Auth MCP Server",
+        instructions="A simple MCP server with simple credential authentication",
+        auth_server_provider=oauth_provider,
+        debug=True,
+        auth=mcp_auth_settings,
+    )
+    # Store server settings for later use in run()
+    app._server_settings = server_settings  # type: ignore[attr-defined]
+
+    @app.custom_route("/login", methods=["GET"])
+    async def login_page_handler(request: Request) -> Response:
+        """Show login form."""
+        state = request.query_params.get("state")
+        if not state:
+            raise HTTPException(400, "Missing state parameter")
+        return await oauth_provider.get_login_page(state)
+
+    @app.custom_route("/login/callback", methods=["POST"])
+    async def login_callback_handler(request: Request) -> Response:
+        """Handle simple authentication callback."""
+        return await oauth_provider.handle_login_callback(request)
+
+    @app.tool()
+    async def get_time() -> dict[str, Any]:
+        """Get the current server time.
+
+        This tool demonstrates that system information can be protected
+        by OAuth authentication. User must be authenticated to access it.
+        """
+
+        now = datetime.datetime.now()
+
+        return {
+            "current_time": now.isoformat(),
+            "timezone": "UTC",  # Simplified for demo
+            "timestamp": now.timestamp(),
+            "formatted": now.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+
+    return app
+
+
+@click.command()
+@click.option("--port", default=8000, help="Port to listen on")
+@click.option(
+    "--transport",
+    default="streamable-http",
+    type=click.Choice(["sse", "streamable-http"]),
+    help="Transport protocol to use ('sse' or 'streamable-http')",
+)
+def main(port: int, transport: Literal["sse", "streamable-http"]) -> int:
+    """Run the simple auth MCP server."""
+    logging.basicConfig(level=logging.INFO)
+
+    auth_settings = SimpleAuthSettings()
+    # Create server settings
+    host = "localhost"
+    server_url = f"http://{host}:{port}"
+    server_settings = ServerSettings(
+        host=host,
+        port=port,
+        server_url=AnyHttpUrl(server_url),
+        auth_callback_path=f"{server_url}/login",
+    )
+
+    mcp_server = create_simple_mcp_server(server_settings, auth_settings)
+    logger.info(f"🚀 MCP Legacy Server running on {server_url}")
+    mcp_server.run(transport=transport, host=host, port=port)
+    return 0
+
+
+if __name__ == "__main__":
+    main()  # type: ignore[call-arg]

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

@@ -0,0 +1,161 @@
+"""MCP Resource Server with Token Introspection.
+
+This server validates tokens via Authorization Server introspection and serves MCP resources.
+Demonstrates RFC 9728 Protected Resource Metadata for AS/RS separation.
+
+NOTE: this is a simplified example for demonstration purposes.
+This is not a production-ready implementation.
+"""
+
+import datetime
+import logging
+from typing import Any, Literal
+
+import click
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.mcpserver.server import MCPServer
+
+from .token_verifier import IntrospectionTokenVerifier
+
+logger = logging.getLogger(__name__)
+
+
+class ResourceServerSettings(BaseSettings):
+    """Settings for the MCP Resource Server."""
+
+    model_config = SettingsConfigDict(env_prefix="MCP_RESOURCE_")
+
+    # Server settings
+    host: str = "localhost"
+    port: int = 8001
+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8001/mcp")
+
+    # Authorization Server settings
+    auth_server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:9000")
+    auth_server_introspection_endpoint: str = "http://localhost:9000/introspect"
+    # No user endpoint needed - we get user data from token introspection
+
+    # MCP settings
+    mcp_scope: str = "user"
+
+    # RFC 8707 resource validation
+    oauth_strict: bool = False
+
+
+def create_resource_server(settings: ResourceServerSettings) -> MCPServer:
+    """Create MCP Resource Server with token introspection.
+
+    This server:
+    1. Provides protected resource metadata (RFC 9728)
+    2. Validates tokens via Authorization Server introspection
+    3. Serves MCP tools and resources
+    """
+    # Create token verifier for introspection with RFC 8707 resource validation
+    token_verifier = IntrospectionTokenVerifier(
+        introspection_endpoint=settings.auth_server_introspection_endpoint,
+        server_url=str(settings.server_url),
+        validate_resource=settings.oauth_strict,  # Only validate when --oauth-strict is set
+    )
+
+    # Create MCPServer server as a Resource Server
+    app = MCPServer(
+        name="MCP Resource Server",
+        instructions="Resource Server that validates tokens via Authorization Server introspection",
+        debug=True,
+        # Auth configuration for RS mode
+        token_verifier=token_verifier,
+        auth=AuthSettings(
+            issuer_url=settings.auth_server_url,
+            required_scopes=[settings.mcp_scope],
+            resource_server_url=settings.server_url,
+        ),
+    )
+    # Store settings for later use in run()
+    app._resource_server_settings = settings  # type: ignore[attr-defined]
+
+    @app.tool()
+    async def get_time() -> dict[str, Any]:
+        """Get the current server time.
+
+        This tool demonstrates that system information can be protected
+        by OAuth authentication. User must be authenticated to access it.
+        """
+
+        now = datetime.datetime.now()
+
+        return {
+            "current_time": now.isoformat(),
+            "timezone": "UTC",  # Simplified for demo
+            "timestamp": now.timestamp(),
+            "formatted": now.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+
+    return app
+
+
+@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(
+    "--transport",
+    default="streamable-http",
+    type=click.Choice(["sse", "streamable-http"]),
+    help="Transport protocol to use ('sse' or 'streamable-http')",
+)
+@click.option(
+    "--oauth-strict",
+    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:
+    """Run the MCP Resource Server.
+
+    This server:
+    - Provides RFC 9728 Protected Resource Metadata
+    - Validates tokens via Authorization Server introspection
+    - Serves MCP tools requiring authentication
+
+    Must be used with a running Authorization Server.
+    """
+    logging.basicConfig(level=logging.INFO)
+
+    try:
+        # Parse auth server URL
+        auth_server_url = AnyHttpUrl(auth_server)
+
+        # Create settings
+        host = "localhost"
+        server_url = f"http://{host}:{port}/mcp"
+        settings = ResourceServerSettings(
+            host=host,
+            port=port,
+            server_url=AnyHttpUrl(server_url),
+            auth_server_url=auth_server_url,
+            auth_server_introspection_endpoint=f"{auth_server}/introspect",
+            oauth_strict=oauth_strict,
+        )
+    except ValueError as e:
+        logger.error(f"Configuration error: {e}")
+        logger.error("Make sure to provide a valid Authorization Server URL")
+        return 1
+
+    try:
+        mcp_server = create_resource_server(settings)
+
+        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)
+        logger.info("Server stopped")
+        return 0
+    except Exception:
+        logger.exception("Server error")
+        return 1
+
+
+if __name__ == "__main__":
+    main()  # type: ignore[call-arg]

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

@@ -0,0 +1,272 @@
+"""Simple OAuth provider for MCP servers.
+
+This module contains a basic OAuth implementation using hardcoded user credentials
+for demonstration purposes. No external authentication provider is required.
+
+NOTE: this is a simplified example for demonstration purposes.
+This is not a production-ready implementation.
+
+"""
+
+import secrets
+import time
+from typing import Any
+
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse, Response
+
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+    construct_redirect_uri,
+)
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+
+class SimpleAuthSettings(BaseSettings):
+    """Simple OAuth settings for demo purposes."""
+
+    model_config = SettingsConfigDict(env_prefix="MCP_")
+
+    # Demo user credentials
+    demo_username: str = "demo_user"
+    demo_password: str = "demo_password"
+
+    # MCP OAuth scope
+    mcp_scope: str = "user"
+
+
+class SimpleOAuthProvider(OAuthAuthorizationServerProvider[AuthorizationCode, RefreshToken, AccessToken]):
+    """Simple OAuth provider for demo purposes.
+
+    This provider handles the OAuth flow by:
+    1. Providing a simple login form for demo credentials
+    2. Issuing MCP tokens after successful authentication
+    3. Maintaining token state for introspection
+    """
+
+    def __init__(self, settings: SimpleAuthSettings, auth_callback_url: str, server_url: str):
+        self.settings = settings
+        self.auth_callback_url = auth_callback_url
+        self.server_url = server_url
+        self.clients: dict[str, OAuthClientInformationFull] = {}
+        self.auth_codes: dict[str, AuthorizationCode] = {}
+        self.tokens: dict[str, AccessToken] = {}
+        self.state_mapping: dict[str, dict[str, str | None]] = {}
+        # Store authenticated user information
+        self.user_data: dict[str, dict[str, Any]] = {}
+
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Get OAuth client information."""
+        return self.clients.get(client_id)
+
+    async def register_client(self, client_info: OAuthClientInformationFull):
+        """Register a new OAuth client."""
+        if not client_info.client_id:
+            raise ValueError("No client_id provided")
+        self.clients[client_info.client_id] = client_info
+
+    async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
+        """Generate an authorization URL for simple login flow."""
+        state = params.state or secrets.token_hex(16)
+
+        # Store state mapping for callback
+        self.state_mapping[state] = {
+            "redirect_uri": str(params.redirect_uri),
+            "code_challenge": params.code_challenge,
+            "redirect_uri_provided_explicitly": str(params.redirect_uri_provided_explicitly),
+            "client_id": client.client_id,
+            "resource": params.resource,  # RFC 8707
+        }
+
+        # Build simple login URL that points to login page
+        auth_url = f"{self.auth_callback_url}?state={state}&client_id={client.client_id}"
+
+        return auth_url
+
+    async def get_login_page(self, state: str) -> HTMLResponse:
+        """Generate login page HTML for the given state."""
+        if not state:
+            raise HTTPException(400, "Missing state parameter")
+
+        # Create simple login form HTML
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <title>MCP Demo Authentication</title>
+            <style>
+                body {{ font-family: Arial, sans-serif; max-width: 500px; margin: 0 auto; padding: 20px; }}
+                .form-group {{ margin-bottom: 15px; }}
+                input {{ width: 100%; padding: 8px; margin-top: 5px; }}
+                button {{ background-color: #4CAF50; color: white; padding: 10px 15px; border: none; cursor: pointer; }}
+            </style>
+        </head>
+        <body>
+            <h2>MCP Demo Authentication</h2>
+            <p>This is a simplified authentication demo. Use the demo credentials below:</p>
+            <p><strong>Username:</strong> demo_user<br>
+            <strong>Password:</strong> demo_password</p>
+
+            <form action="{self.server_url.rstrip("/")}/login/callback" method="post">
+                <input type="hidden" name="state" value="{state}">
+                <div class="form-group">
+                    <label>Username:</label>
+                    <input type="text" name="username" value="demo_user" required>
+                </div>
+                <div class="form-group">
+                    <label>Password:</label>
+                    <input type="password" name="password" value="demo_password" required>
+                </div>
+                <button type="submit">Sign In</button>
+            </form>
+        </body>
+        </html>
+        """
+
+        return HTMLResponse(content=html_content)
+
+    async def handle_login_callback(self, request: Request) -> Response:
+        """Handle login form submission callback."""
+        form = await request.form()
+        username = form.get("username")
+        password = form.get("password")
+        state = form.get("state")
+
+        if not username or not password or not state:
+            raise HTTPException(400, "Missing username, password, or state parameter")
+
+        # Ensure we have strings, not UploadFile objects
+        if not isinstance(username, str) or not isinstance(password, str) or not isinstance(state, str):
+            raise HTTPException(400, "Invalid parameter types")
+
+        redirect_uri = await self.handle_simple_callback(username, password, state)
+        return RedirectResponse(url=redirect_uri, status_code=302)
+
+    async def handle_simple_callback(self, username: str, password: str, state: str) -> str:
+        """Handle simple authentication callback and return redirect URI."""
+        state_data = self.state_mapping.get(state)
+        if not state_data:
+            raise HTTPException(400, "Invalid state parameter")
+
+        redirect_uri = state_data["redirect_uri"]
+        code_challenge = state_data["code_challenge"]
+        redirect_uri_provided_explicitly = state_data["redirect_uri_provided_explicitly"] == "True"
+        client_id = state_data["client_id"]
+        resource = state_data.get("resource")  # RFC 8707
+
+        # These are required values from our own state mapping
+        assert redirect_uri is not None
+        assert code_challenge is not None
+        assert client_id is not None
+
+        # Validate demo credentials
+        if username != self.settings.demo_username or password != self.settings.demo_password:
+            raise HTTPException(401, "Invalid credentials")
+
+        # Create MCP authorization code
+        new_code = f"mcp_{secrets.token_hex(16)}"
+        auth_code = AuthorizationCode(
+            code=new_code,
+            client_id=client_id,
+            redirect_uri=AnyHttpUrl(redirect_uri),
+            redirect_uri_provided_explicitly=redirect_uri_provided_explicitly,
+            expires_at=time.time() + 300,
+            scopes=[self.settings.mcp_scope],
+            code_challenge=code_challenge,
+            resource=resource,  # RFC 8707
+            subject=username,
+        )
+        self.auth_codes[new_code] = auth_code
+
+        # Store user data
+        self.user_data[username] = {
+            "username": username,
+            "user_id": f"user_{secrets.token_hex(8)}",
+            "authenticated_at": time.time(),
+        }
+
+        del self.state_mapping[state]
+        return construct_redirect_uri(redirect_uri, code=new_code, state=state)
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        """Load an authorization code."""
+        return self.auth_codes.get(authorization_code)
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        """Exchange authorization code for tokens."""
+        if authorization_code.code not in self.auth_codes:
+            raise ValueError("Invalid authorization code")
+        if not client.client_id:
+            raise ValueError("No client_id provided")
+
+        # Generate MCP access token
+        mcp_token = f"mcp_{secrets.token_hex(32)}"
+
+        # Store MCP token
+        self.tokens[mcp_token] = AccessToken(
+            token=mcp_token,
+            client_id=client.client_id,
+            scopes=authorization_code.scopes,
+            expires_at=int(time.time()) + 3600,
+            resource=authorization_code.resource,  # RFC 8707
+            subject=authorization_code.subject,
+        )
+
+        # Store user data mapping for this token
+        self.user_data[mcp_token] = {
+            "username": self.settings.demo_username,
+            "user_id": f"user_{secrets.token_hex(8)}",
+            "authenticated_at": time.time(),
+        }
+
+        del self.auth_codes[authorization_code.code]
+
+        return OAuthToken(
+            access_token=mcp_token,
+            token_type="Bearer",
+            expires_in=3600,
+            scope=" ".join(authorization_code.scopes),
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        """Load and validate an access token."""
+        access_token = self.tokens.get(token)
+        if not access_token:
+            return None
+
+        # Check if expired
+        if access_token.expires_at and access_token.expires_at < time.time():
+            del self.tokens[token]
+            return None
+
+        return access_token
+
+    async def load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshToken | None:
+        """Load a refresh token - not supported in this example."""
+        return None
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Exchange refresh token - not supported in this example."""
+        raise NotImplementedError("Refresh tokens not supported")
+
+    # TODO(Marcelo): The type hint is wrong. We need to fix, and test to check if it works.
+    async def revoke_token(self, token: str, token_type_hint: str | None = None) -> None:  # type: ignore
+        """Revoke a token."""
+        if token in self.tokens:
+            del self.tokens[token]

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

@@ -0,0 +1,108 @@
+"""Example token verifier implementation using OAuth 2.0 Token Introspection (RFC 7662)."""
+
+import logging
+from typing import Any
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+from mcp.shared.auth_utils import check_resource_allowed, resource_url_from_server_url
+
+logger = logging.getLogger(__name__)
+
+
+class IntrospectionTokenVerifier(TokenVerifier):
+    """Example token verifier that uses OAuth 2.0 Token Introspection (RFC 7662).
+
+    This is a simple example implementation for demonstration purposes.
+    Production implementations should consider:
+    - Connection pooling and reuse
+    - More sophisticated error handling
+    - Rate limiting and retry logic
+    - Comprehensive configuration options
+    """
+
+    def __init__(
+        self,
+        introspection_endpoint: str,
+        server_url: str,
+        validate_resource: bool = False,
+    ):
+        self.introspection_endpoint = introspection_endpoint
+        self.server_url = server_url
+        self.validate_resource = validate_resource
+        self.resource_url = resource_url_from_server_url(server_url)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token via introspection endpoint."""
+        import httpx
+
+        # Validate URL to prevent SSRF attacks
+        if not self.introspection_endpoint.startswith(("https://", "http://localhost", "http://127.0.0.1")):
+            logger.warning(f"Rejecting introspection endpoint with unsafe scheme: {self.introspection_endpoint}")
+            return None
+
+        # Configure secure HTTP client
+        timeout = httpx.Timeout(10.0, connect=5.0)
+        limits = httpx.Limits(max_connections=10, max_keepalive_connections=5)
+
+        async with httpx.AsyncClient(
+            timeout=timeout,
+            limits=limits,
+            verify=True,  # Enforce SSL verification
+        ) as client:
+            try:
+                response = await client.post(
+                    self.introspection_endpoint,
+                    data={"token": token},
+                    headers={"Content-Type": "application/x-www-form-urlencoded"},
+                )
+
+                if response.status_code != 200:
+                    logger.debug(f"Token introspection returned status {response.status_code}")
+                    return None
+
+                data = response.json()
+                if not data.get("active", False):
+                    return None
+
+                # RFC 8707 resource validation (only when --oauth-strict is set)
+                if self.validate_resource and not self._validate_resource(data):
+                    logger.warning(f"Token resource validation failed. Expected: {self.resource_url}")
+                    return None
+
+                return AccessToken(
+                    token=token,
+                    client_id=data.get("client_id", "unknown"),
+                    scopes=data.get("scope", "").split() if data.get("scope") else [],
+                    expires_at=data.get("exp"),
+                    resource=data.get("aud"),  # Include resource in token
+                    subject=data.get("sub"),  # RFC 7662 subject (resource owner)
+                    claims=data,
+                )
+            except Exception as e:
+                logger.warning(f"Token introspection failed: {e}")
+                return None
+
+    def _validate_resource(self, token_data: dict[str, Any]) -> bool:
+        """Validate token was issued for this resource server."""
+        if not self.server_url or not self.resource_url:
+            return False  # Fail if strict validation requested but URLs missing
+
+        # Check 'aud' claim first (standard JWT audience)
+        aud: list[str] | str | None = token_data.get("aud")
+        if isinstance(aud, list):
+            for audience in aud:
+                if self._is_valid_resource(audience):
+                    return True
+            return False
+        elif aud:
+            return self._is_valid_resource(aud)
+
+        # No resource binding - invalid per RFC 8707
+        return False
+
+    def _is_valid_resource(self, resource: str) -> bool:
+        """Check if resource matches this server using hierarchical matching."""
+        if not self.resource_url:
+            return False
+
+        return check_resource_allowed(requested_resource=self.resource_url, configured_resource=resource)