Merge branch 'main' into lifespan_ctx_readme

Author: johnbikes

.github/workflows/publish-docs-manually.yml

@@ -30,4 +30,4 @@ jobs:
             mkdocs-material-
 
       - run: uv sync --frozen --group docs
-      - run: uv run --no-sync mkdocs gh-deploy --force
+      - run: uv run --frozen --no-sync mkdocs gh-deploy --force

.github/workflows/publish-pypi.yml

@@ -22,7 +22,7 @@ jobs:
         run: uv python install 3.12
 
       - name: Build
-        run: uv build
+        run: uv build --frozen
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
@@ -79,4 +79,4 @@ jobs:
             mkdocs-material-
 
       - run: uv sync --frozen --group docs
-      - run: uv run --no-sync mkdocs gh-deploy --force
+      - run: uv run --frozen --no-sync mkdocs gh-deploy --force

.github/workflows/shared.yml

@@ -44,5 +44,5 @@ jobs:
         run: uv sync --frozen --all-extras --python ${{ matrix.python-version }}
 
       - name: Run pytest
-        run: uv run --no-sync pytest
+        run: uv run --frozen --no-sync pytest
     continue-on-error: true

README.md

@@ -423,43 +423,42 @@ The `elicit()` method returns an `ElicitationResult` with:
 
 Authentication can be used by servers that want to expose tools accessing protected resources.
 
-`mcp.server.auth` implements an OAuth 2.0 server interface, which servers can use by
-providing an implementation of the `OAuthAuthorizationServerProvider` protocol.
+`mcp.server.auth` implements OAuth 2.1 resource server functionality, where MCP servers act as Resource Servers (RS) that validate tokens issued by separate Authorization Servers (AS). This follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) and implements RFC 9728 (Protected Resource Metadata) for AS discovery.
+
+MCP servers can use authentication by providing an implementation of the `TokenVerifier` protocol:
 
 ```python
 from mcp import FastMCP
-from mcp.server.auth.provider import OAuthAuthorizationServerProvider
-from mcp.server.auth.settings import (
-    AuthSettings,
-    ClientRegistrationOptions,
-    RevocationOptions,
-)
+from mcp.server.auth.provider import TokenVerifier, TokenInfo
+from mcp.server.auth.settings import AuthSettings
 
 
-class MyOAuthServerProvider(OAuthAuthorizationServerProvider):
-    # See an example on how to implement at `examples/servers/simple-auth`
-    ...
+class MyTokenVerifier(TokenVerifier):
+    # Implement token validation logic (typically via token introspection)
+    async def verify_token(self, token: str) -> TokenInfo:
+        # Verify with your authorization server
+        ...
 
 
 mcp = FastMCP(
     "My App",
-    auth_server_provider=MyOAuthServerProvider(),
+    token_verifier=MyTokenVerifier(),
     auth=AuthSettings(
-        issuer_url="https://myapp.com",
-        revocation_options=RevocationOptions(
-            enabled=True,
-        ),
-        client_registration_options=ClientRegistrationOptions(
-            enabled=True,
-            valid_scopes=["myscope", "myotherscope"],
-            default_scopes=["myscope"],
-        ),
-        required_scopes=["myscope"],
+        issuer_url="https://auth.example.com",
+        resource_server_url="http://localhost:3001",
+        required_scopes=["mcp:read", "mcp:write"],
     ),
 )
 ```
 
-See [OAuthAuthorizationServerProvider](src/mcp/server/auth/provider.py) for more details.
+For a complete example with separate Authorization Server and Resource Server implementations, see [`examples/servers/simple-auth/`](examples/servers/simple-auth/).
+
+**Architecture:**
+- **Authorization Server (AS)**: Handles OAuth flows, user authentication, and token issuance
+- **Resource Server (RS)**: Your MCP server that validates tokens and serves protected resources
+- **Client**: Discovers AS through RFC 9728, obtains tokens, and uses them with the MCP server
+
+See [TokenVerifier](src/mcp/server/auth/provider.py) for more details on implementing token validation.
 
 ## Running Your Server
 
@@ -830,6 +829,67 @@ if __name__ == "__main__":
 
 Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
 
+#### Structured Output Support
+
+The low-level server supports structured output for tools, allowing you to return both human-readable content and machine-readable structured data. Tools can define an `outputSchema` to validate their structured output:
+
+```python
+from types import Any
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+
+server = Server("example-server")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="calculate",
+            description="Perform mathematical calculations",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "expression": {"type": "string", "description": "Math expression"}
+                },
+                "required": ["expression"],
+            },
+            outputSchema={
+                "type": "object",
+                "properties": {
+                    "result": {"type": "number"},
+                    "expression": {"type": "string"},
+                },
+                "required": ["result", "expression"],
+            },
+        )
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    if name == "calculate":
+        expression = arguments["expression"]
+        try:
+            result = eval(expression)  # Use a safe math parser
+            structured = {"result": result, "expression": expression}
+
+            # low-level server will validate structured output against the tool's
+            # output schema, and automatically serialize it into a TextContent block
+            # for backwards compatibility with pre-2025-06-18 clients.
+            return structured
+        except Exception as e:
+            raise ValueError(f"Calculation error: {str(e)}")
+```
+
+Tools can return data in three ways:
+1. **Content only**: Return a list of content blocks (default behavior before spec revision 2025-06-18)
+2. **Structured data only**: Return a dictionary that will be serialized to JSON (Introduced in spec revision 2025-06-18)
+3. **Both**: Return a tuple of (content, structured_data) preferred option to use for backwards compatibility
+
+When an `outputSchema` is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early.
+
 ### Writing MCP Clients
 
 The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):

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

@@ -160,8 +160,7 @@ async def connect(self):
         print(f"🔗 Attempting to connect to {self.server_url}...")
 
         try:
-            # Set up callback server
-            callback_server = CallbackServer(port=3000)
+            callback_server = CallbackServer(port=3030)
             callback_server.start()
 
             async def callback_handler() -> tuple[str, str | None]:
@@ -175,7 +174,7 @@ async def callback_handler() -> tuple[str, str | None]:
 
             client_metadata_dict = {
                 "client_name": "Simple Auth Client",
-                "redirect_uris": ["http://localhost:3000/callback"],
+                "redirect_uris": ["http://localhost:3030/callback"],
                 "grant_types": ["authorization_code", "refresh_token"],
                 "response_types": ["code"],
                 "token_endpoint_auth_method": "client_secret_post",

examples/servers/simple-auth/README.md

@@ -1,91 +1,129 @@
-# Simple MCP Server with GitHub OAuth Authentication
+# MCP OAuth Authentication Demo
 
-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 example demonstrates OAuth 2.0 authentication with the Model Context Protocol using **separate Authorization Server (AS) and Resource Server (RS)** to comply with the new RFC 9728 specification.
 
-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
+## Running the Servers
 
+### Step 1: Start Authorization Server
 
-## Prerequisites
+```bash
+# Navigate to the simple-auth directory
+cd examples/servers/simple-auth
+
+# Start Authorization Server on port 9000
+uv run mcp-simple-auth-as --port=9000
+```
 
-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
+**What it provides:**
+- OAuth 2.0 flows (registration, authorization, token exchange)
+- Simple credential-based authentication (no external provider needed)  
+- Token introspection endpoint for Resource Servers (`/introspect`)
 
-## Required Environment Variables
+---
 
-You MUST set these environment variables before running the server:
+### Step 2: Start Resource Server (MCP Server)
 
 ```bash
-export MCP_GITHUB_GITHUB_CLIENT_ID="your_client_id_here"
-export MCP_GITHUB_GITHUB_CLIENT_SECRET="your_client_secret_here"
-```
+# In another terminal, navigate to the simple-auth directory
+cd examples/servers/simple-auth
 
-The server will not start without these environment variables properly set.
+# Start Resource Server on port 8001, connected to Authorization Server
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000  --transport=streamable-http
 
+# With RFC 8707 strict resource validation (recommended for production)
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000  --transport=streamable-http --oauth-strict
 
-## Running the Server
+```
 
-```bash
-# Set environment variables first (see above)
 
-# Run the server
-uv run mcp-simple-auth
+### Step 3: Test with Client
+
+```bash
+cd examples/clients/simple-auth-client
+# Start client with streamable HTTP
+MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=streamable_http uv run mcp-simple-auth-client
 ```
 
-The server will start on `http://localhost:8000`.
 
-### Transport Options
+## How It Works
 
-This server supports multiple transport protocols that can run on the same port:
+### RFC 9728 Discovery
 
-#### SSE (Server-Sent Events) - Default
+**Client → Resource Server:**
 ```bash
-uv run mcp-simple-auth
-# or explicitly:
-uv run mcp-simple-auth --transport sse
+curl http://localhost:8001/.well-known/oauth-protected-resource
+```
+```json
+{
+  "resource": "http://localhost:8001",
+  "authorization_servers": ["http://localhost:9000"]
+}
 ```
 
-SSE transport provides endpoint:
-- `/sse`
-
-#### Streamable HTTP
+**Client → Authorization Server:**
 ```bash
-uv run mcp-simple-auth --transport streamable-http
+curl http://localhost:9000/.well-known/oauth-authorization-server
+```
+```json
+{
+  "issuer": "http://localhost:9000",
+  "authorization_endpoint": "http://localhost:9000/authorize",
+  "token_endpoint": "http://localhost:9000/token"
+}
 ```
 
-Streamable HTTP transport provides endpoint:
-- `/mcp`
 
+## Legacy MCP Server as Authorization Server (Backwards Compatibility)
 
-This ensures backward compatibility without needing multiple server instances. When using SSE transport (`--transport sse`), only the `/sse` endpoint is available.
+For backwards compatibility with older MCP implementations, a legacy server is provided that acts as an Authorization Server (following the old spec where MCP servers could optionally provide OAuth):
 
-## Available Tool
+### Running the Legacy Server
 
-### get_user_profile
+```bash
+# Start legacy authorization server on port 8002
+uv run mcp-simple-auth-legacy --port=8002
+```
+
+**Differences from the new architecture:**
+- **MCP server acts as AS:** The MCP server itself provides OAuth endpoints (old spec behavior)
+- **No separate RS:** The server handles both authentication and MCP tools
+- **Local token validation:** Tokens are validated internally without introspection
+- **No RFC 9728 support:** Does not provide `/.well-known/oauth-protected-resource`
+- **Direct OAuth discovery:** OAuth metadata is at the MCP server's URL
 
-The only tool in this simple example. Returns the authenticated user's GitHub profile information.
+### Testing with Legacy Server
+
+```bash
+# Test with client (will automatically fall back to legacy discovery)
+cd examples/clients/simple-auth-client
+MCP_SERVER_PORT=8002 MCP_TRANSPORT_TYPE=streamable_http uv run mcp-simple-auth-client
+```
 
-**Required scope**: `user`
+The client will:
+1. Try RFC 9728 discovery at `/.well-known/oauth-protected-resource` (404 on legacy server)
+2. Fall back to direct OAuth discovery at `/.well-known/oauth-authorization-server`
+3. Complete authentication with the MCP server acting as its own AS
 
-**Returns**: GitHub user profile data including username, email, bio, etc.
+This ensures existing MCP servers (which could optionally act as Authorization Servers under the old spec) continue to work while the ecosystem transitions to the new architecture where MCP servers are Resource Servers only.
 
+## Manual Testing
 
-## Troubleshooting
+### Test Discovery
+```bash
+# Test Resource Server discovery endpoint (new architecture)
+curl -v http://localhost:8001/.well-known/oauth-protected-resource
 
-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`)
+# Test Authorization Server metadata
+curl -v http://localhost:9000/.well-known/oauth-authorization-server
+```
 
-You can use [Inspector](https://github.com/modelcontextprotocol/inspector) to test Auth
+### Test Token Introspection
+```bash
+# After getting a token through OAuth flow:
+curl -X POST http://localhost:9000/introspect \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "token=your_access_token"
+```