Skip to content

Commit 1941154

Browse files
dgeniodgenio
committed
fix: move stateless mode docs from frozen README.md to README.v2.md
README.md is frozen at v1 per CI checks. Move the Understanding Stateless Mode section and the refined note to README.v2.md instead. Update code examples to use MCPServer (formerly FastMCP).
1 parent e7f7723 commit 1941154

File tree

2 files changed

+150
-147
lines changed

2 files changed

+150
-147
lines changed

‎README.md‎

Lines changed: 1 addition & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1243,7 +1243,7 @@ Note that `uv run mcp run` or `uv run mcp dev` only supports server using FastMC
12431243

12441244
### Streamable HTTP Transport
12451245

1246-
> **Note**: Streamable HTTP transport is the recommended transport for production deployments. For serverless and load-balanced environments, consider using `stateless_http=True` and `json_response=True`. See [Understanding Stateless Mode](#understanding-stateless-mode) for guidance on choosing between stateful and stateless operation.
1246+
> **Note**: Streamable HTTP transport is the recommended transport for production deployments. Use `stateless_http=True` and `json_response=True` for optimal scalability.
12471247
12481248
<!-- snippet-source examples/snippets/servers/streamable_config.py -->
12491249
```python
@@ -1355,151 +1355,6 @@ The streamable HTTP transport supports:
13551355
- JSON or SSE response formats
13561356
- Better scalability for multi-node deployments
13571357

1358-
#### Understanding Stateless Mode
1359-
1360-
The Streamable HTTP transport can operate in two modes: **stateful** (default) and **stateless**. Understanding the difference is important for choosing the right deployment model.
1361-
1362-
##### What "Stateless" Means
1363-
1364-
In **stateless mode** (`stateless_http=True`), each HTTP request creates a completely independent MCP session that exists only for the duration of that single request:
1365-
1366-
- **No session tracking**: No `Mcp-Session-Id` header is used or required
1367-
- **Per-request lifecycle**: Each request initializes a fresh server instance, processes the request, and terminates
1368-
- **No state persistence**: No information is retained between requests
1369-
- **No event store**: Resumability features are disabled
1370-
1371-
This is fundamentally different from **stateful mode** (default), where:
1372-
1373-
- A session persists across multiple requests
1374-
- The `Mcp-Session-Id` header links requests to an existing session
1375-
- Server state (e.g., subscriptions, context) is maintained between calls
1376-
- Event stores can provide resumability if the connection drops
1377-
1378-
##### MCP Features Impacted by Stateless Mode
1379-
1380-
When running in stateless mode, certain MCP features are unavailable or behave differently:
1381-
1382-
| Feature | Stateful Mode | Stateless Mode |
1383-
|---------|---------------|----------------|
1384-
| **Server Notifications** | ✅ Supported | ❌ Not available<sup>1</sup> |
1385-
| **Resource Subscriptions** | ✅ Supported | ❌ Not available<sup>1</sup> |
1386-
| **Multi-turn Context** | ✅ Maintained | ❌ Lost between requests<sup>2</sup> |
1387-
| **Long-running Tools** | ✅ Can use notifications for progress | ⚠️ Must complete within request timeout |
1388-
| **Event Resumability** | ✅ With event store | ❌ Not applicable |
1389-
| **Tools/Resources/Prompts** | ✅ Fully supported | ✅ Fully supported |
1390-
| **Concurrent Requests** | ⚠️ One per session | ✅ Unlimited<sup>3</sup> |
1391-
1392-
<sup>1</sup> Server-initiated notifications require a persistent connection to deliver updates
1393-
<sup>2</sup> Each request starts fresh; client must provide all necessary context
1394-
<sup>3</sup> Each request is independent, enabling horizontal scaling
1395-
1396-
##### When to Use Stateless Mode
1397-
1398-
**Stateless mode is ideal for:**
1399-
1400-
- **Serverless Deployments**: AWS Lambda, Cloud Functions, or similar FaaS platforms where instances are ephemeral
1401-
- **Load-Balanced Multi-Node**: Deploying across multiple servers without sticky sessions
1402-
- **Stateless APIs**: Services where each request is self-contained (e.g., data lookups, calculations)
1403-
- **High Concurrency**: Scenarios requiring many simultaneous independent operations
1404-
- **Simplified Operations**: Avoiding session management complexity
1405-
1406-
**Use stateful mode when:**
1407-
1408-
- Server needs to push notifications to clients (e.g., progress updates, real-time events)
1409-
- Resources require subscriptions with change notifications
1410-
- Tools maintain conversation state across multiple turns
1411-
- Long-running operations need to report progress asynchronously
1412-
- Connection resumability is required
1413-
1414-
##### Example: Stateless Configuration
1415-
1416-
```python
1417-
from mcp.server.fastmcp import FastMCP
1418-
1419-
# Stateless server - each request is independent
1420-
mcp = FastMCP(
1421-
"StatelessAPI",
1422-
stateless_http=True, # Enable stateless mode
1423-
json_response=True, # Recommended for stateless
1424-
)
1425-
1426-
@mcp.tool()
1427-
def calculate(a: int, b: int, operation: str) -> int:
1428-
"""Stateless calculation tool."""
1429-
operations = {"add": a + b, "multiply": a * b}
1430-
return operations[operation]
1431-
1432-
# Each request will:
1433-
# 1. Initialize a new server instance
1434-
# 2. Process the calculate tool call
1435-
# 3. Return the result
1436-
# 4. Terminate the instance
1437-
```
1438-
1439-
##### Deployment Patterns
1440-
1441-
###### Pattern 1: Pure Stateless (Recommended)
1442-
1443-
```python
1444-
# Best for: Serverless, auto-scaling environments
1445-
mcp = FastMCP("MyServer", stateless_http=True, json_response=True)
1446-
1447-
# Clients can connect to any instance
1448-
# Load balancer doesn't need session affinity
1449-
```
1450-
1451-
###### Pattern 2: Stateful with Sticky Sessions
1452-
1453-
```python
1454-
# Best for: When you need notifications but have load balancing
1455-
mcp = FastMCP("MyServer", stateless_http=False) # Default
1456-
1457-
# Load balancer must use sticky sessions based on Mcp-Session-Id header
1458-
# ALB/NGINX can route by header value to maintain session affinity
1459-
```
1460-
1461-
###### Pattern 3: Hybrid Approach
1462-
1463-
```python
1464-
# Deploy both modes side-by-side
1465-
stateless_mcp = FastMCP("StatelessAPI", stateless_http=True)
1466-
stateful_mcp = FastMCP("StatefulAPI", stateless_http=False)
1467-
1468-
app = Starlette(routes=[
1469-
Mount("/api/stateless", app=stateless_mcp.streamable_http_app()),
1470-
Mount("/api/stateful", app=stateful_mcp.streamable_http_app()),
1471-
])
1472-
```
1473-
1474-
##### Technical Details
1475-
1476-
**Session Lifecycle in Stateless Mode:**
1477-
1478-
1. Client sends HTTP POST request to `/mcp` endpoint
1479-
2. Server creates ephemeral `StreamableHTTPServerTransport` (no session ID)
1480-
3. Server initializes fresh `Server` instance with `stateless=True` flag
1481-
4. Request is processed using the ephemeral transport
1482-
5. Response is sent back to client
1483-
6. Transport and server instance are immediately terminated
1484-
1485-
**Performance Characteristics:**
1486-
1487-
- **Initialization overhead**: Each request pays the cost of server initialization
1488-
- **Memory efficiency**: No long-lived sessions consuming memory
1489-
- **Scalability**: Excellent horizontal scaling with no state synchronization
1490-
- **Latency**: Slightly higher per-request latency due to initialization
1491-
1492-
**Stateless Mode Checklist:**
1493-
1494-
When designing for stateless mode, ensure:
1495-
1496-
- ✅ Tools are self-contained and don't rely on previous calls
1497-
- ✅ All required context is passed in each request
1498-
- ✅ Tools complete synchronously within request timeout
1499-
- ✅ No server notifications or subscriptions are needed
1500-
- ✅ Client handles any necessary state management
1501-
- ✅ Operations are idempotent where possible
1502-
15031358
#### CORS Configuration for Browser-Based Clients
15041359

15051360
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:

‎README.v2.md‎

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1239,7 +1239,7 @@ Note that `uv run mcp run` or `uv run mcp dev` only supports server using MCPSer
12391239

12401240
### Streamable HTTP Transport
12411241

1242-
> **Note**: Streamable HTTP transport is the recommended transport for production deployments. Use `stateless_http=True` and `json_response=True` for optimal scalability.
1242+
> **Note**: Streamable HTTP transport is the recommended transport for production deployments. For serverless and load-balanced environments, consider using `stateless_http=True` and `json_response=True`. See [Understanding Stateless Mode](#understanding-stateless-mode) for guidance on choosing between stateful and stateless operation.
12431243
12441244
<!-- snippet-source examples/snippets/servers/streamable_config.py -->
12451245
```python
@@ -1350,6 +1350,154 @@ The streamable HTTP transport supports:
13501350
- JSON or SSE response formats
13511351
- Better scalability for multi-node deployments
13521352

1353+
#### Understanding Stateless Mode
1354+
1355+
The Streamable HTTP transport can operate in two modes: **stateful** (default) and **stateless**. Understanding the difference is important for choosing the right deployment model.
1356+
1357+
##### What "Stateless" Means
1358+
1359+
In **stateless mode** (`stateless_http=True`), each HTTP request creates a completely independent MCP session that exists only for the duration of that single request:
1360+
1361+
- **No session tracking**: No `Mcp-Session-Id` header is used or required
1362+
- **Per-request lifecycle**: Each request initializes a fresh server instance, processes the request, and terminates
1363+
- **No state persistence**: No information is retained between requests
1364+
- **No event store**: Resumability features are disabled
1365+
1366+
This is fundamentally different from **stateful mode** (default), where:
1367+
1368+
- A session persists across multiple requests
1369+
- The `Mcp-Session-Id` header links requests to an existing session
1370+
- Server state (e.g., subscriptions, context) is maintained between calls
1371+
- Event stores can provide resumability if the connection drops
1372+
1373+
##### MCP Features Impacted by Stateless Mode
1374+
1375+
When running in stateless mode, certain MCP features are unavailable or behave differently:
1376+
1377+
| Feature | Stateful Mode | Stateless Mode |
1378+
|---------|---------------|----------------|
1379+
| **Server Notifications** | ✅ Supported | ❌ Not available<sup>1</sup> |
1380+
| **Resource Subscriptions** | ✅ Supported | ❌ Not available<sup>1</sup> |
1381+
| **Multi-turn Context** | ✅ Maintained | ❌ Lost between requests<sup>2</sup> |
1382+
| **Long-running Tools** | ✅ Can use notifications for progress | ⚠️ Must complete within request timeout |
1383+
| **Event Resumability** | ✅ With event store | ❌ Not applicable |
1384+
| **Tools/Resources/Prompts** | ✅ Fully supported | ✅ Fully supported |
1385+
| **Concurrent Requests** | ⚠️ One per session | ✅ Unlimited<sup>3</sup> |
1386+
1387+
<sup>1</sup> Server-initiated notifications require a persistent connection to deliver updates
1388+
<sup>2</sup> Each request starts fresh; client must provide all necessary context
1389+
<sup>3</sup> Each request is independent, enabling horizontal scaling
1390+
1391+
##### When to Use Stateless Mode
1392+
1393+
**Stateless mode is ideal for:**
1394+
1395+
- **Serverless Deployments**: AWS Lambda, Cloud Functions, or similar FaaS platforms where instances are ephemeral
1396+
- **Load-Balanced Multi-Node**: Deploying across multiple servers without sticky sessions
1397+
- **Stateless APIs**: Services where each request is self-contained (e.g., data lookups, calculations)
1398+
- **High Concurrency**: Scenarios requiring many simultaneous independent operations
1399+
- **Simplified Operations**: Avoiding session management complexity
1400+
1401+
**Use stateful mode when:**
1402+
1403+
- Server needs to push notifications to clients (e.g., progress updates, real-time events)
1404+
- Resources require subscriptions with change notifications
1405+
- Tools maintain conversation state across multiple turns
1406+
- Long-running operations need to report progress asynchronously
1407+
- Connection resumability is required
1408+
1409+
##### Example: Stateless Configuration
1410+
1411+
```python
1412+
from mcp.server.mcpserver import MCPServer
1413+
1414+
# Stateless server - each request is independent
1415+
mcp = MCPServer(
1416+
"StatelessAPI",
1417+
stateless_http=True, # Enable stateless mode
1418+
json_response=True, # Recommended for stateless
1419+
)
1420+
1421+
@mcp.tool()
1422+
def calculate(a: int, b: int, operation: str) -> int:
1423+
"""Stateless calculation tool."""
1424+
operations = {"add": a + b, "multiply": a * b}
1425+
return operations[operation]
1426+
1427+
# Each request will:
1428+
# 1. Initialize a new server instance
1429+
# 2. Process the calculate tool call
1430+
# 3. Return the result
1431+
# 4. Terminate the instance
1432+
```
1433+
1434+
##### Deployment Patterns
1435+
1436+
###### Pattern 1: Pure Stateless (Recommended)
1437+
1438+
```python
1439+
# Best for: Serverless, auto-scaling environments
1440+
mcp = MCPServer("MyServer", stateless_http=True, json_response=True)
1441+
1442+
# Clients can connect to any instance
1443+
# Load balancer doesn't need session affinity
1444+
```
1445+
1446+
###### Pattern 2: Stateful with Sticky Sessions
1447+
1448+
```python
1449+
# Best for: When you need notifications but have load balancing
1450+
mcp = MCPServer("MyServer", stateless_http=False) # Default
1451+
1452+
# Load balancer must use sticky sessions based on Mcp-Session-Id header
1453+
# ALB/NGINX can route by header value to maintain session affinity
1454+
```
1455+
1456+
###### Pattern 3: Hybrid Approach
1457+
1458+
```python
1459+
from starlette.applications import Starlette
1460+
from starlette.routing import Mount
1461+
1462+
# Deploy both modes side-by-side
1463+
stateless_mcp = MCPServer("StatelessAPI", stateless_http=True)
1464+
stateful_mcp = MCPServer("StatefulAPI", stateless_http=False)
1465+
1466+
app = Starlette(routes=[
1467+
Mount("/api/stateless", app=stateless_mcp.streamable_http_app()),
1468+
Mount("/api/stateful", app=stateful_mcp.streamable_http_app()),
1469+
])
1470+
```
1471+
1472+
##### Technical Details
1473+
1474+
**Session Lifecycle in Stateless Mode:**
1475+
1476+
1. Client sends HTTP POST request to `/mcp` endpoint
1477+
2. Server creates ephemeral `StreamableHTTPServerTransport` (no session ID)
1478+
3. Server initializes fresh `Server` instance with `stateless=True` flag
1479+
4. Request is processed using the ephemeral transport
1480+
5. Response is sent back to client
1481+
6. Transport and server instance are immediately terminated
1482+
1483+
**Performance Characteristics:**
1484+
1485+
- **Initialization overhead**: Each request pays the cost of server initialization
1486+
- **Memory efficiency**: No long-lived sessions consuming memory
1487+
- **Scalability**: Excellent horizontal scaling with no state synchronization
1488+
- **Latency**: Slightly higher per-request latency due to initialization
1489+
1490+
**Stateless Mode Checklist:**
1491+
1492+
When designing for stateless mode, ensure:
1493+
1494+
- ✅ Tools are self-contained and don't rely on previous calls
1495+
- ✅ All required context is passed in each request
1496+
- ✅ Tools complete synchronously within request timeout
1497+
- ✅ No server notifications or subscriptions are needed
1498+
- ✅ Client handles any necessary state management
1499+
- ✅ Operations are idempotent where possible
1500+
13531501
#### CORS Configuration for Browser-Based Clients
13541502

13551503
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:

0 commit comments

Comments
 (0)