docs: Update examples to use stateless HTTP with JSON responses #1499
Conversation
Update README and example code to consistently recommend and demonstrate stateless HTTP with JSON responses (stateless_http=True, json_response=True) as the recommended pattern for production deployments. Changes: - Update quickstart example to use stateless HTTP + JSON and make it executable - Update all streamable HTTP mounting examples with recommended config - Update OAuth server example with recommended config - Reorder streamable_config.py to show recommended option first - Change quickstart integration instructions to use Claude Code with HTTP - Clarify that stateless HTTP + JSON is optimal for scalability This encourages users away from stdio/SSE/stateful HTTP patterns that have extra complexity and makes servers less reliable for most use cases.
Change from 'uv run mcp dev' to the simpler two-step approach: 1. Run server with 'uv run --with mcp server.py' 2. Open inspector with 'npx -y @modelcontextprotocol/inspector' and connect manually This avoids the complexity of mcp dev trying to manage stdio vs HTTP transport and gives users more control over the connection.
There was a problem hiding this comment.
It feels odd to me to go so all-in on stateless/json_response on every example when "stateless" on the MCP protocol spec doesn't even appear in a search yet.
I'm wondering if this causes potentially more confusion than help when the spec doesn't really provide a canonical description of how this is implemented?
Also I know @bhosmer-ant and @pja-ant are currently deep in discussions with the transport working group for what stateless looks like at the protocol layer, so I feel like going all in like this might be premature?
I think it'd be fine to increase the prominence of the stateless option (kind of like we do on TS? https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#without-session-management-recommended) but to make it look like the default seems a bit much?
felixweinberger
added
needs more eyes
2 participants
Summary
Updates README and example code to consistently recommend and demonstrate stateless HTTP with JSON responses as the recommended pattern for production deployments.
Changes
stateless_http=True, json_response=Trueand make it executablestreamable_config.pyto show recommended option firstRationale
This encourages users away from stdio/SSE/stateful HTTP patterns that have extra complexity and makes servers less reliable for most use cases. Stateless HTTP with JSON responses provides: