docs: clarify Streamable HTTP stateless mode semantics and usage

[dgenio]

Summary

This PR improves the documentation for Streamable HTTP stateless_http mode in the Python SDK by clarifying what "stateless" means in the MCP context, which features are impacted, and when this mode is appropriate to use.

Motivation

Several production deployments rely on Streamable HTTP transport, and stateless mode is particularly attractive for serverless and load-balanced environments. However, the current documentation doesn't fully explain:

• What "stateless" actually means in terms of session lifecycle
• Which MCP features are unavailable or behave differently in stateless mode
• When to choose stateless vs stateful operation
• How to deploy stateless servers effectively

This directly addresses the concerns raised in issue #1696 about unclear semantics, limitations, and naming.

Changes

Added: Comprehensive "Understanding Stateless Mode" Section

Located after the Streamable HTTP transport examples, this new documentation includes:

1. Clear Definition

• Explains the per-request session model used in stateless mode
• Contrasts with stateful mode's persistent sessions
• Details what happens at the transport level

2. Feature Compatibility Table

Shows which MCP features work in each mode:

Feature	Stateful	Stateless
Server Notifications	✅	❌
Resource Subscriptions	✅	❌
Multi-turn Context	✅	❌
Long-running Tools	✅	⚠️
Tools/Resources/Prompts	✅	✅
Concurrent Requests	⚠️	✅

With helpful footnotes explaining the limitations.

3. Usage Guidance

Stateless mode is ideal for:

• Serverless deployments (AWS Lambda, Cloud Functions, etc.)
• Load-balanced multi-node deployments without sticky sessions
• Stateless APIs where each request is self-contained
• High concurrency scenarios
• Simplified operations without session management

Stateful mode is needed for:

• Server notifications and subscriptions
• Multi-turn conversation state
• Long-running operations with progress updates
• Connection resumability

4. Three Deployment Patterns

• Pure Stateless (recommended for serverless/auto-scaling)
• Stateful with Sticky Sessions (notifications + load balancing)
• Hybrid Approach (both modes side-by-side)

Each with code examples.

5. Technical Details

• Step-by-step session lifecycle in stateless mode
• Performance characteristics (initialization overhead, memory efficiency, scalability)
• Stateless mode design checklist

6. Updated Introduction

Changed the blanket recommendation for stateless mode to a more nuanced statement that directs users to the new section for guidance.

Type of Change

• Documentation only
• Bug fix
• New feature
• Breaking change

Testing

• Documentation builds without errors
• Markdown formatting is correct
• Internal links work properly
• Code examples are syntactically valid

Notes

• This is a documentation-only change; no behavior is modified
• Examples reference existing code in examples/servers/simple-streamablehttp-stateless/
• If maintainers prefer alternative terminology (e.g., "ephemeral mode"), I'm happy to update accordingly

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own changes
• I have commented my code where necessary
• My changes generate no new warnings
• Any dependent changes have been merged and published

Closes #1696

[dgenio]

This PR is still relevant — the README still has the blanket recommendation to use stateless_http=True without explaining the tradeoffs, and there's no documentation anywhere covering stateless mode semantics or limitations.

The diff should apply cleanly or nearly so since the relevant README section hasn't changed.

A couple of questions for maintainers:

1. Location: Given the README is already quite long, would you prefer this content go in docs/ (e.g., docs/transports.md or similar) instead of the README? Happy to move it.
2. Review: This has been open for 3+ months with no reviews. Would appreciate a look when you get a chance — it's a docs-only change addressing a real gap in user guidance.

I can rebase on latest main if that helps move things forward.

[dgenio]

Just rebased on latest main (3 commits, no conflicts) to keep this current.

This PR has been open for 4+ months and remains relevant. Since it was opened, several new issues have confirmed that the missing documentation around stateless mode is causing real user confusion:

• Lifespan enters and exits for each request when stateless_http=True #1304 — lifespan runs per-request in stateless mode (now subsumed by Redesign lifespan: separate server-scoped and session-scoped lifetimes #2113)
• Redesign lifespan: separate server-scoped and session-scoped lifetimes #2113 — lifespan redesign (v2 / breaking change) explicitly names stateless mode lifecycle as a root cause
• Improve log clarity for "Terminating session: None" in stateless mode #2329 / fix(streamable-http): reduce stateless termination log noise #2357 — users mistake "Terminating session: None" for a connection error
• Image/ImageContent serialization fails in stateless HTTP mode #2376 — image serialization silently fails in stateless mode, blocking Claude.ai deployments

All of these trace back to the same gap: users don't know what stateless mode actually does, what it doesn't support, and when to use it. The blanket recommendation in README.v2.md (Use stateless_http=True and json_response=True for optimal scalability) still points people toward stateless mode without explaining the tradeoffs.

@felixweinberger — would appreciate a look when you have a moment. Happy to move the content to docs/transports.md or adjust scope if that fits better with the v2 docs direction.