Merge branch 'modelcontextprotocol:main' into main

Author: ramjibc

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

@@ -19,6 +19,7 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4

.github/workflows/publish-pypi.yml

@@ -16,6 +16,7 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12
@@ -67,6 +68,7 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4

.github/workflows/shared.yml

@@ -13,6 +13,7 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - name: Install the project
         run: uv sync --frozen --all-extras --dev --python 3.12
@@ -29,6 +30,7 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - name: Install the project
         run: uv sync --frozen --all-extras --dev --python 3.12
@@ -37,10 +39,11 @@ jobs:
         run: uv run --no-sync pyright
 
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -49,9 +52,11 @@ jobs:
         uses: astral-sh/setup-uv@v3
         with:
           enable-cache: true
+          version: 0.7.2
 
       - name: Install the project
         run: uv sync --frozen --all-extras --dev --python ${{ matrix.python-version }}
 
       - name: Run pytest
         run: uv run --no-sync pytest
+    continue-on-error: true

README.md

@@ -160,7 +160,7 @@ from dataclasses import dataclass
 
 from fake_database import Database  # Replace with your actual DB type
 
-from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.fastmcp import FastMCP
 
 # Create a named server
 mcp = FastMCP("My App")
@@ -192,9 +192,10 @@ mcp = FastMCP("My App", lifespan=app_lifespan)
 
 # Access type-safe lifespan context in tools
 @mcp.tool()
-def query_db(ctx: Context) -> str:
+def query_db() -> str:
     """Tool that uses initialized resources"""
-    db = ctx.request_context.lifespan_context.db
+    ctx = mcp.get_context()
+    db = ctx.request_context.lifespan_context["db"]
     return db.query()
 ```
 
@@ -314,27 +315,42 @@ async def long_task(files: list[str], ctx: Context) -> str:
 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 `OAuthServerProvider` protocol.
+providing an implementation of the `OAuthAuthorizationServerProvider` protocol.
 
-```
-mcp = FastMCP("My App",
-        auth_provider=MyOAuthServerProvider(),
-        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"],
+```python
+from mcp import FastMCP
+from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+from mcp.server.auth.settings import (
+    AuthSettings,
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+
+
+class MyOAuthServerProvider(OAuthAuthorizationServerProvider):
+    # See an example on how to implement at `examples/servers/simple-auth`
+    ...
+
+
+mcp = FastMCP(
+    "My App",
+    auth_server_provider=MyOAuthServerProvider(),
+    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"],
+    ),
 )
 ```
 
-See [OAuthServerProvider](src/mcp/server/auth/provider.py) for more details.
+See [OAuthAuthorizationServerProvider](src/mcp/server/auth/provider.py) for more details.
 
 ## Running Your Server
 
@@ -387,6 +403,8 @@ python server.py
 mcp run server.py
 ```
 
+Note that `mcp run` or `mcp dev` only supports server using FastMCP and not the low-level server variant.
+
 ### Streamable HTTP Transport
 
 > **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
@@ -400,6 +418,9 @@ mcp = FastMCP("StatefulServer")
 # Stateless server (no session persistence)
 mcp = FastMCP("StatelessServer", stateless_http=True)
 
+# Stateless server (no session persistence, no sse stream with supported client)
+mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
+
 # Run server with streamable_http transport
 mcp.run(transport="streamable-http")
 ```
@@ -426,21 +447,28 @@ mcp = FastMCP(name="MathServer", stateless_http=True)
 
 
 @mcp.tool(description="A simple add tool")
-def add_two(n: int) -> str:
+def add_two(n: int) -> int:
     return n + 2
 ```
 
 ```python
 # main.py
+import contextlib
 from fastapi import FastAPI
 from mcp.echo import echo
 from mcp.math import math
 
 
-app = FastAPI()
+# Create a combined lifespan to manage both session managers
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with contextlib.AsyncExitStack() as stack:
+        await stack.enter_async_context(echo.mcp.session_manager.run())
+        await stack.enter_async_context(math.mcp.session_manager.run())
+        yield
 
-# Use the session manager's lifespan
-app = FastAPI(lifespan=lambda app: echo.mcp.session_manager.run())
+
+app = FastAPI(lifespan=lifespan)
 app.mount("/echo", echo.mcp.streamable_http_app())
 app.mount("/math", math.mcp.streamable_http_app())
 ```
@@ -449,19 +477,18 @@ For low level server with Streamable HTTP implementations, see:
 - Stateful server: [`examples/servers/simple-streamablehttp/`](examples/servers/simple-streamablehttp/)
 - Stateless server: [`examples/servers/simple-streamablehttp-stateless/`](examples/servers/simple-streamablehttp-stateless/)
 
-
-
 The streamable HTTP transport supports:
 - Stateful and stateless operation modes
 - Resumability with event stores
-- JSON or SSE response formats  
+- JSON or SSE response formats
 - Better scalability for multi-node deployments
 
-
 ### Mounting to an Existing ASGI Server
 
 > **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
 
+By default, SSE servers are mounted at `/sse` and Streamable HTTP servers are mounted at `/mcp`. You can customize these paths using the methods described below.
+
 You can mount the SSE server to an existing ASGI server using the `sse_app` method. This allows you to integrate the SSE server with other ASGI applications.
 
 ```python
@@ -692,6 +719,8 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
+
 ### 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):
@@ -780,6 +809,60 @@ async def main():
             tool_result = await session.call_tool("echo", {"message": "hello"})
 ```
 
+### OAuth Authentication for Clients
+
+The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
+
+```python
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+
+class CustomTokenStorage(TokenStorage):
+    """Simple in-memory token storage implementation."""
+
+    async def get_tokens(self) -> OAuthToken | None:
+        pass
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        pass
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        pass
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        pass
+
+
+async def main():
+    # Set up OAuth authentication
+    oauth_auth = OAuthClientProvider(
+        server_url="https://api.example.com",
+        client_metadata=OAuthClientMetadata(
+            client_name="My Client",
+            redirect_uris=["http://localhost:3000/callback"],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        ),
+        storage=CustomTokenStorage(),
+        redirect_handler=lambda url: print(f"Visit: {url}"),
+        callback_handler=lambda: ("auth_code", None),
+    )
+
+    # Use with streamable HTTP client
+    async with streamablehttp_client(
+        "https://api.example.com/mcp", auth=oauth_auth
+    ) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            # Authenticated session ready
+```
+
+For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).
+
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:

examples/clients/simple-auth-client/README.md

@@ -0,0 +1,74 @@
+# Simple Auth Client Example
+
+A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport.
+
+## Features
+
+- OAuth 2.0 authentication with PKCE
+- Support for both StreamableHTTP and SSE transports
+- Interactive command-line interface
+
+## Installation
+
+```bash
+cd examples/clients/simple-auth-client
+uv sync --reinstall 
+```
+
+## Usage
+
+### 1. Start an MCP server with OAuth support
+
+```bash
+# Example with mcp-simple-auth
+cd path/to/mcp-simple-auth
+uv run mcp-simple-auth --transport streamable-http --port 3001
+```
+
+### 2. Run the client
+
+```bash
+uv run mcp-simple-auth-client
+
+# Or with custom server URL
+MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
+
+# Use SSE transport
+MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
+```
+
+### 3. Complete OAuth flow
+
+The client will open your browser for authentication. After completing OAuth, you can use commands:
+
+- `list` - List available tools
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments  
+- `quit` - Exit
+
+## Example
+
+```
+🔐 Simple MCP Auth Client
+Connecting to: http://localhost:3001
+
+Please visit the following URL to authorize the application:
+http://localhost:3001/authorize?response_type=code&client_id=...
+
+✅ Connected to MCP server at http://localhost:3001
+
+mcp> list
+📋 Available tools:
+1. echo - Echo back the input text
+
+mcp> call echo {"text": "Hello, world!"}
+🔧 Tool 'echo' result:
+Hello, world!
+
+mcp> quit
+👋 Goodbye!
+```
+
+## Configuration
+
+- `MCP_SERVER_PORT` - Server URL (default: 8000)
+- `MCP_TRANSPORT_TYPE` - Transport type: `streamable_http` (default) or `sse`

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

@@ -0,0 +1 @@
+"""Simple OAuth client for MCP simple-auth server."""