Add support for remote-oauth-support

Author: ravibits

examples/servers/simple-auth-remote/README.md

@@ -0,0 +1,91 @@
+# Simple MCP Server with GitHub OAuth Authentication
+
+This is a simple example of an MCP server with GitHub OAuth authentication. It demonstrates the essential components needed for OAuth integration with just a single tool.
+
+This is just an example of a server that uses auth, an official GitHub mcp server is [here](https://github.com/github/github-mcp-server)
+
+## Overview
+
+This simple demo to show to set up a server with:
+- GitHub OAuth2 authorization flow
+- Single tool: `get_user_profile` to retrieve GitHub user information
+
+
+## Prerequisites
+
+1. Create a GitHub OAuth App:
+   - Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App
+   - Application name: Any name (e.g., "Simple MCP Auth Demo")
+   - Homepage URL: `http://localhost:8000`
+   - Authorization callback URL: `http://localhost:8000/github/callback`
+   - Click "Register application"
+   - Note down your Client ID and Client Secret
+
+## Required Environment Variables
+
+You MUST set these environment variables before running the server:
+
+```bash
+export MCP_GITHUB_GITHUB_CLIENT_ID="your_client_id_here"
+export MCP_GITHUB_GITHUB_CLIENT_SECRET="your_client_secret_here"
+```
+
+The server will not start without these environment variables properly set.
+
+
+## Running the Server
+
+```bash
+# Set environment variables first (see above)
+
+# Run the server
+uv run mcp-simple-auth
+```
+
+The server will start on `http://localhost:8000`.
+
+### Transport Options
+
+This server supports multiple transport protocols that can run on the same port:
+
+#### SSE (Server-Sent Events) - Default
+```bash
+uv run mcp-simple-auth
+# or explicitly:
+uv run mcp-simple-auth --transport sse
+```
+
+SSE transport provides endpoint:
+- `/sse`
+
+#### Streamable HTTP
+```bash
+uv run mcp-simple-auth --transport streamable-http
+```
+
+Streamable HTTP transport provides endpoint:
+- `/mcp`
+
+
+This ensures backward compatibility without needing multiple server instances. When using SSE transport (`--transport sse`), only the `/sse` endpoint is available.
+
+## Available Tool
+
+### get_user_profile
+
+The only tool in this simple example. Returns the authenticated user's GitHub profile information.
+
+**Required scope**: `user`
+
+**Returns**: GitHub user profile data including username, email, bio, etc.
+
+
+## Troubleshooting
+
+If the server fails to start, check:
+1. Environment variables `MCP_GITHUB_GITHUB_CLIENT_ID` and `MCP_GITHUB_GITHUB_CLIENT_SECRET` are set
+2. The GitHub OAuth app callback URL matches `http://localhost:8000/github/callback`
+3. No other service is using port 8000
+4. The transport specified is valid (`sse` or `streamable-http`)
+
+You can use [Inspector](https://github.com/modelcontextprotocol/inspector) to test Auth

examples/servers/simple-auth-remote/mcp_simple_remote_auth/__init__.py

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

examples/servers/simple-auth-remote/mcp_simple_remote_auth/__main__.py

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

examples/servers/simple-auth-remote/mcp_simple_remote_auth/server.py

@@ -0,0 +1,117 @@
+"""Simple MCP Server with GitHub OAuth Authentication."""
+
+import logging
+import secrets
+import time
+from typing import Any, Literal
+
+import click
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse, Response
+
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+    TokenValidator,
+    construct_redirect_uri,
+)
+from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
+from mcp.server.fastmcp.server import FastMCP
+from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+logger = logging.getLogger(__name__)
+
+
+class ServerSettings(BaseSettings):
+    """Settings for the simple GitHub MCP server."""
+
+    model_config = SettingsConfigDict(env_prefix="MCP_GITHUB_")
+
+    # Server settings
+    host: str = "localhost"
+    port: int = 8000
+    server_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8000")
+    mcp_scope: str = "user"
+
+    def __init__(self, **data):
+        """Initialize settings with values from environment variables.
+
+        Note: github_client_id and github_client_secret are required but can be
+        loaded automatically from environment variables (MCP_GITHUB_GITHUB_CLIENT_ID
+        and MCP_GITHUB_GITHUB_CLIENT_SECRET) and don't need to be passed explicitly.
+        """
+        super().__init__(**data)
+
+
+def create_simple_mcp_server(settings: ServerSettings) -> FastMCP:
+    """Create a simple FastMCP server with GitHub OAuth."""
+
+    auth_settings = AuthSettings(
+        issuer_url=settings.server_url,
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=[settings.mcp_scope],
+            default_scopes=[settings.mcp_scope],
+        ),
+        required_scopes=[settings.mcp_scope],
+    )
+
+    app = FastMCP(
+        name="Simple GitHub MCP Server",
+        instructions="A simple MCP server with GitHub OAuth authentication",
+        host=settings.host,
+        port=settings.port,
+        debug=True,
+        auth=auth_settings,
+        token_validator=TokenValidator(),
+        protected_resource_metadata={"resource": "asdasd", "authorization_servers": ["https://auth.devramp.ai"], "scopes_supported": ["user"]}
+    )
+
+    @app.tool()
+    async def get_user_profile() -> dict[str, Any]:
+        """Get the authenticated user's GitHub profile information.
+
+        This is the only tool in our simple example. It requires the 'user' scope.
+        """
+        return {"user": "asdasd"}
+
+    return app
+
+
+@click.command()
+@click.option("--port", default=8000, help="Port to listen on")
+@click.option("--host", default="localhost", help="Host to bind to")
+@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, host: str, transport: Literal["sse", "streamable-http"]) -> int:
+    """Run the simple GitHub MCP server."""
+    logging.basicConfig(level=logging.INFO)
+
+    try:
+        # No hardcoded credentials - all from environment variables
+        settings = ServerSettings(host=host, port=port)
+    except ValueError as e:
+        logger.error(
+            "Failed to load settings. Make sure environment variables are set:"
+        )
+        logger.error("  MCP_GITHUB_GITHUB_CLIENT_ID=<your-client-id>")
+        logger.error("  MCP_GITHUB_GITHUB_CLIENT_SECRET=<your-client-secret>")
+        logger.error(f"Error: {e}")
+        return 1
+
+    mcp_server = create_simple_mcp_server(settings)
+    logger.info(f"Starting server with {transport} transport")
+    mcp_server.run(transport=transport)
+    return 0

examples/servers/simple-auth-remote/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "mcp-simple-remote-auth"
+version = "0.1.0"
+description = "A simple MCP server demonstrating OAuth authentication"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Anthropic, PBC." }]
+license = { text = "MIT" }
+dependencies = [
+    "anyio>=4.5",
+    "click>=8.1.0",
+    "httpx>=0.27",
+    "mcp",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.5.2",
+    "sse-starlette>=1.6.1",
+    "uvicorn>=0.23.1; sys_platform != 'emscripten'",
+]
+
+[project.scripts]
+mcp-simple-remote-auth = "mcp_simple_remote_auth.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mcp_simple_remote_auth"]
+
+[tool.uv]
+dev-dependencies = ["pyright>=1.1.391", "pytest>=8.3.4", "ruff>=0.8.5"]

src/mcp/server/auth/middleware/bearer_auth.py

@@ -10,7 +10,7 @@
 from starlette.requests import HTTPConnection
 from starlette.types import Receive, Scope, Send
 
-from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvider
+from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvider, TokenValidator
 
 
 class AuthenticatedUser(SimpleUser):
@@ -21,6 +21,42 @@ def __init__(self, auth_info: AccessToken):
         self.access_token = auth_info
         self.scopes = auth_info.scopes
 
+class JWTBearerTokenAuthBackend(AuthenticationBackend):
+    """
+    Authentication backend that validates Bearer tokens.
+    """
+
+    def __init__(
+        self,
+        provider: TokenValidator[AccessToken],
+    ):
+        self.provider = provider
+
+    async def authenticate(self, conn: HTTPConnection):
+        auth_header = next(
+            (
+                conn.headers.get(key)
+                for key in conn.headers
+                if key.lower() == "authorization"
+            ),
+            None,
+        )
+        if not auth_header or not auth_header.lower().startswith("bearer "):
+            return None
+
+        token = auth_header[7:]  # Remove "Bearer " prefix
+
+        # Validate the token with the provider
+        auth_info = await self.provider.validate_token(token)
+
+
+        if not auth_info:
+            return None
+
+        if auth_info.expires_at and auth_info.expires_at < int(time.time()):
+            return None
+
+        return AuthCredentials(auth_info.scopes), AuthenticatedUser(auth_info)
 
 class BearerAuthBackend(AuthenticationBackend):
     """

src/mcp/server/auth/provider.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Generic, Literal, Protocol, TypeVar
+from typing import Generic, Literal, Protocol, TypeVar, Any
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
 from pydantic import AnyHttpUrl, BaseModel
@@ -10,6 +10,14 @@
 )
 
 
+# Define type variables
+AccessTokenT = TypeVar('AccessTokenT', bound='AccessToken')
+
+class TokenValidator(Generic[AccessTokenT], BaseModel):
+    async def validate_token(self, token: str) -> AccessTokenT | None:
+        ...
+
+
 class AuthorizationParams(BaseModel):
     state: str | None
     scopes: list[str] | None