Clarify semantics, limitations, and naming for stateless HTTP mode

[dgenio]

Description

Summary

The SDK exposes a stateless_http mode for Streamable HTTP, where each request is handled with a new transport/session. This is useful for some deployment environments, but it has important implications:

• no true session continuity,
• repeated initialization overhead,
• some MCP features are effectively unavailable.

These tradeoffs are not clearly documented today, and the name “stateless” can be misleading.

Problems

• Session semantics: Creating a fresh session per HTTP request means:
  • multi-turn interactions are harder (the server cannot rely on server-side state),
  • progress notifications and long-running operations have limited usefulness.
• Performance: Initial negotiation and setup happen on every request.
• Feature behavior: Certain MCP features implicitly depend on session continuity but may silently degrade in stateless mode.
• Naming: “stateless” suggests no server-side state at all, but in practice there is still per-request state and protocol semantics.

Proposal

1. Document limitations explicitly

   • List which features and patterns work differently or not at all in stateless mode:
     • long-running tools,
     • interactions that rely on server-side session state,
     • any features that require persistent IDs beyond a single request.

2. Clarify recommended usage

   • Explain when stateless_http is appropriate (e.g., simple request/response tools behind serverless endpoints).
   • Provide patterns for using sticky sessions or other mechanisms when stateful behavior is required.

3. Consider naming improvements

   • If possible without breaking compatibility, clarify naming in code and docs (e.g., “ephemeral” or “per-request” mode), or:
   • at least add documentation that explains what “stateless” means in this context.

Why this matters

• User expectations: Server authors and operators can make informed decisions about whether to use stateless mode.
• Debuggability: Clear semantics reduce surprises when features behave differently.
• Performance: Documentation can encourage appropriate deployment patterns (e.g., caching initialization results where possible).

Acceptance criteria

• Documentation for Streamable HTTP and stateless_http explicitly describes:
  • behavior,
  • limitations,
  • recommended use cases.
• It is clear which MCP features require stateful sessions.
• The naming and semantics of stateless mode are explained to avoid confusion.

References

No response

[maxisbey]

Thanks for the report. Closing this as it's been fixed in v2, which is now released (see #3044). Feel free to reopen if you still hit it on v2.

_{AI Disclaimer}