-
Notifications
You must be signed in to change notification settings - Fork 2.8k
docs: Update examples to use stateless HTTP with JSON responses #1499
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
59e2314 to
859f633
Compare
|
Thanks! I've updated the PR to remove Also will note that the |
…onse Remove stateless_http=True from examples to avoid going "all-in" on stateless before it's properly documented in the MCP spec. Keep json_response=True for client compatibility. Changes: - Remove stateless_http from quickstart and other examples - Keep json_response=True as recommended option
8cf6ea9 to
8dbdfb2
Compare
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: