Merge branch 'main' into fastmpc-logging-progress-example

Author: stevebillings

.gitattribute

@@ -0,0 +1,2 @@
+# Generated
+uv.lock  linguist-generated=true

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 cover/
 
 # Translations
@@ -162,9 +163,12 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # vscode
 .vscode/
 .windsurfrules
 **/CLAUDE.local.md
+
+# claude code
+.claude/

README.md

@@ -31,22 +31,32 @@
     - [Prompts](#prompts)
     - [Images](#images)
     - [Context](#context)
+      - [Getting Context in Functions](#getting-context-in-functions)
+      - [Context Properties and Methods](#context-properties-and-methods)
     - [Completions](#completions)
     - [Elicitation](#elicitation)
     - [Sampling](#sampling)
     - [Logging and Notifications](#logging-and-notifications)
     - [Authentication](#authentication)
     - [FastMCP Properties](#fastmcp-properties)
-    - [Session Properties](#session-properties-and-methods)
+    - [Session Properties and Methods](#session-properties-and-methods)
     - [Request Context Properties](#request-context-properties)
   - [Running Your Server](#running-your-server)
     - [Development Mode](#development-mode)
     - [Claude Desktop Integration](#claude-desktop-integration)
     - [Direct Execution](#direct-execution)
     - [Streamable HTTP Transport](#streamable-http-transport)
+      - [CORS Configuration for Browser-Based Clients](#cors-configuration-for-browser-based-clients)
     - [Mounting to an Existing ASGI Server](#mounting-to-an-existing-asgi-server)
+      - [StreamableHTTP servers](#streamablehttp-servers)
+        - [Basic mounting](#basic-mounting)
+        - [Host-based routing](#host-based-routing)
+        - [Multiple servers with path configuration](#multiple-servers-with-path-configuration)
+        - [Path configuration at initialization](#path-configuration-at-initialization)
+      - [SSE servers](#sse-servers)
   - [Advanced Usage](#advanced-usage)
     - [Low-Level Server](#low-level-server)
+      - [Structured Output Support](#structured-output-support)
     - [Writing MCP Clients](#writing-mcp-clients)
     - [Client Display Utilities](#client-display-utilities)
     - [OAuth Authentication for Clients](#oauth-authentication-for-clients)
@@ -400,7 +410,7 @@ def get_weather(city: str) -> WeatherData:
     """Get weather for a city - returns structured data."""
     # Simulated weather data
     return WeatherData(
-        temperature=72.5,
+        temperature=22.5,
         humidity=45.0,
         condition="sunny",
         wind_speed=5.2,
@@ -1143,6 +1153,11 @@ app = Starlette(
     ],
     lifespan=lifespan,
 )
+
+# Note: Clients connect to http://localhost:8000/echo/mcp and http://localhost:8000/math/mcp
+# To mount at the root of each path (e.g., /echo instead of /echo/mcp):
+# echo_mcp.settings.streamable_http_path = "/"
+# math_mcp.settings.streamable_http_path = "/"
 ```
 
 _Full example: [examples/snippets/servers/streamable_starlette_mount.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_starlette_mount.py)_
@@ -1160,12 +1175,204 @@ The streamable HTTP transport supports:
 - JSON or SSE response formats
 - Better scalability for multi-node deployments
 
+#### CORS Configuration for Browser-Based Clients
+
+If you'd like your server to be accessible by browser-based MCP clients, you'll need to configure CORS headers. The `Mcp-Session-Id` header must be exposed for browser clients to access it:
+
+```python
+from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
+
+# Create your Starlette app first
+starlette_app = Starlette(routes=[...])
+
+# Then wrap it with CORS middleware
+starlette_app = CORSMiddleware(
+    starlette_app,
+    allow_origins=["*"],  # Configure appropriately for production
+    allow_methods=["GET", "POST", "DELETE"],  # MCP streamable HTTP methods
+    expose_headers=["Mcp-Session-Id"],
+)
+```
+
+This configuration is necessary because:
+
+- The MCP streamable HTTP transport uses the `Mcp-Session-Id` header for session management
+- Browsers restrict access to response headers unless explicitly exposed via CORS
+- Without this configuration, browser-based clients won't be able to read the session ID from initialization responses
+
 ### Mounting to an Existing ASGI Server
 
 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.
 
 For more information on mounting applications in Starlette, see the [Starlette documentation](https://www.starlette.io/routing/#submounting-routes).
 
+#### StreamableHTTP servers
+
+You can mount the StreamableHTTP server to an existing ASGI server using the `streamable_http_app` method. This allows you to integrate the StreamableHTTP server with other ASGI applications.
+
+##### Basic mounting
+
+<!-- snippet-source examples/snippets/servers/streamable_http_basic_mounting.py -->
+```python
+"""
+Basic example showing how to mount StreamableHTTP server in Starlette.
+
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_http_basic_mounting:app --reload
+"""
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server.fastmcp import FastMCP
+
+# Create MCP server
+mcp = FastMCP("My App")
+
+
+@mcp.tool()
+def hello() -> str:
+    """A simple hello tool"""
+    return "Hello from MCP!"
+
+
+# Mount the StreamableHTTP server to the existing ASGI server
+app = Starlette(
+    routes=[
+        Mount("/", app=mcp.streamable_http_app()),
+    ]
+)
+```
+
+_Full example: [examples/snippets/servers/streamable_http_basic_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_basic_mounting.py)_
+<!-- /snippet-source -->
+
+##### Host-based routing
+
+<!-- snippet-source examples/snippets/servers/streamable_http_host_mounting.py -->
+```python
+"""
+Example showing how to mount StreamableHTTP server using Host-based routing.
+
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_http_host_mounting:app --reload
+"""
+
+from starlette.applications import Starlette
+from starlette.routing import Host
+
+from mcp.server.fastmcp import FastMCP
+
+# Create MCP server
+mcp = FastMCP("MCP Host App")
+
+
+@mcp.tool()
+def domain_info() -> str:
+    """Get domain-specific information"""
+    return "This is served from mcp.acme.corp"
+
+
+# Mount using Host-based routing
+app = Starlette(
+    routes=[
+        Host("mcp.acme.corp", app=mcp.streamable_http_app()),
+    ]
+)
+```
+
+_Full example: [examples/snippets/servers/streamable_http_host_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_host_mounting.py)_
+<!-- /snippet-source -->
+
+##### Multiple servers with path configuration
+
+<!-- snippet-source examples/snippets/servers/streamable_http_multiple_servers.py -->
+```python
+"""
+Example showing how to mount multiple StreamableHTTP servers with path configuration.
+
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_http_multiple_servers:app --reload
+"""
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server.fastmcp import FastMCP
+
+# Create multiple MCP servers
+api_mcp = FastMCP("API Server")
+chat_mcp = FastMCP("Chat Server")
+
+
+@api_mcp.tool()
+def api_status() -> str:
+    """Get API status"""
+    return "API is running"
+
+
+@chat_mcp.tool()
+def send_message(message: str) -> str:
+    """Send a chat message"""
+    return f"Message sent: {message}"
+
+
+# Configure servers to mount at the root of each path
+# This means endpoints will be at /api and /chat instead of /api/mcp and /chat/mcp
+api_mcp.settings.streamable_http_path = "/"
+chat_mcp.settings.streamable_http_path = "/"
+
+# Mount the servers
+app = Starlette(
+    routes=[
+        Mount("/api", app=api_mcp.streamable_http_app()),
+        Mount("/chat", app=chat_mcp.streamable_http_app()),
+    ]
+)
+```
+
+_Full example: [examples/snippets/servers/streamable_http_multiple_servers.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_multiple_servers.py)_
+<!-- /snippet-source -->
+
+##### Path configuration at initialization
+
+<!-- snippet-source examples/snippets/servers/streamable_http_path_config.py -->
+```python
+"""
+Example showing path configuration during FastMCP initialization.
+
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_http_path_config:app --reload
+"""
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server.fastmcp import FastMCP
+
+# Configure streamable_http_path during initialization
+# This server will mount at the root of wherever it's mounted
+mcp_at_root = FastMCP("My Server", streamable_http_path="/")
+
+
+@mcp_at_root.tool()
+def process_data(data: str) -> str:
+    """Process some data"""
+    return f"Processed: {data}"
+
+
+# Mount at /process - endpoints will be at /process instead of /process/mcp
+app = Starlette(
+    routes=[
+        Mount("/process", app=mcp_at_root.streamable_http_app()),
+    ]
+)
+```
+
+_Full example: [examples/snippets/servers/streamable_http_path_config.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_path_config.py)_
+<!-- /snippet-source -->
+
 #### SSE servers
 
 > **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
@@ -1940,6 +2147,7 @@ MCP servers declare capabilities during initialization:
 
 ## Documentation
 
+- [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)

examples/servers/simple-resource/mcp_simple_resource/server.py

@@ -2,6 +2,7 @@
 import click
 import mcp.types as types
 from mcp.server.lowlevel import Server
+from mcp.server.lowlevel.helper_types import ReadResourceContents
 from pydantic import AnyUrl, FileUrl
 from starlette.requests import Request
 
@@ -46,15 +47,15 @@ async def list_resources() -> list[types.Resource]:
         ]
 
     @app.read_resource()
-    async def read_resource(uri: AnyUrl) -> str | bytes:
+    async def read_resource(uri: AnyUrl):
         if uri.path is None:
             raise ValueError(f"Invalid resource path: {uri}")
         name = uri.path.replace(".txt", "").lstrip("/")
 
         if name not in SAMPLE_RESOURCES:
             raise ValueError(f"Unknown resource: {uri}")
 
-        return SAMPLE_RESOURCES[name]["content"]
+        return [ReadResourceContents(content=SAMPLE_RESOURCES[name]["content"], mime_type="text/plain")]
 
     if transport == "sse":
         from mcp.server.sse import SseServerTransport

examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py

@@ -9,6 +9,7 @@
 from mcp.server.lowlevel import Server
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
 from starlette.routing import Mount
 from starlette.types import Receive, Scope, Send
 
@@ -123,6 +124,15 @@ async def lifespan(app: Starlette) -> AsyncIterator[None]:
         lifespan=lifespan,
     )
 
+    # Wrap ASGI application with CORS middleware to expose Mcp-Session-Id header
+    # for browser-based clients (ensures 500 errors get proper CORS headers)
+    starlette_app = CORSMiddleware(
+        starlette_app,
+        allow_origins=["*"],  # Allow all origins - adjust as needed for production
+        allow_methods=["GET", "POST", "DELETE"],  # MCP streamable HTTP methods
+        expose_headers=["Mcp-Session-Id"],
+    )
+
     import uvicorn
 
     uvicorn.run(starlette_app, host="127.0.0.1", port=port)

examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py

@@ -10,6 +10,7 @@
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from pydantic import AnyUrl
 from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
 from starlette.routing import Mount
 from starlette.types import Receive, Scope, Send
 
@@ -148,6 +149,15 @@ async def lifespan(app: Starlette) -> AsyncIterator[None]:
         lifespan=lifespan,
     )
 
+    # Wrap ASGI application with CORS middleware to expose Mcp-Session-Id header
+    # for browser-based clients (ensures 500 errors get proper CORS headers)
+    starlette_app = CORSMiddleware(
+        starlette_app,
+        allow_origins=["*"],  # Allow all origins - adjust as needed for production
+        allow_methods=["GET", "POST", "DELETE"],  # MCP streamable HTTP methods
+        expose_headers=["Mcp-Session-Id"],
+    )
+
     import uvicorn
 
     uvicorn.run(starlette_app, host="127.0.0.1", port=port)

examples/snippets/servers/streamable_http_basic_mounting.py

@@ -0,0 +1,28 @@
+"""
+Basic example showing how to mount StreamableHTTP server in Starlette.
+
+Run from the repository root:
+    uvicorn examples.snippets.servers.streamable_http_basic_mounting:app --reload
+"""
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from mcp.server.fastmcp import FastMCP
+
+# Create MCP server
+mcp = FastMCP("My App")
+
+
+@mcp.tool()
+def hello() -> str:
+    """A simple hello tool"""
+    return "Hello from MCP!"
+
+
+# Mount the StreamableHTTP server to the existing ASGI server
+app = Starlette(
+    routes=[
+        Mount("/", app=mcp.streamable_http_app()),
+    ]
+)