Skip to content

Conversation

@domdomegg
Copy link
Member

Summary

Updates README and example code to consistently recommend and demonstrate stateless HTTP with JSON responses as the recommended pattern for production deployments.

Changes

  • Update quickstart example to use stateless_http=True, json_response=True 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 transport
  • Clarify that stateless HTTP + JSON is optimal for scalability

Rationale

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:

  • Better scalability (no session state management)
  • Simpler deployment (works across multiple instances)
  • More reliability (simpler error recovery without SSE stream parsing)
  • Lower complexity (no connection/session management overhead)

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.
Copy link
Contributor

@felixweinberger felixweinberger left a 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?

@felixweinberger felixweinberger added needs more eyes documentation Improvements or additions to documentation labels Oct 23, 2025
@domdomegg domdomegg force-pushed the adamj/stateless-http-json-examples branch from 59e2314 to 859f633 Compare November 18, 2025 14:39
@domdomegg
Copy link
Member Author

domdomegg commented Nov 18, 2025

Thanks! I've updated the PR to remove stateless_http=True from all the examples where it was newly added - see 8dbdfb2.

Also will note that the stateless_http implementation is already supported by the spec, see 2.5.1. "A server using the Streamable HTTP transport MAY assign a session ID at initialization time" - stateless_http in the Python SDK = just not doing this 'MAY' component. But can see there may be other transports changes soon anyways so won't push this further for now.

…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
@domdomegg domdomegg force-pushed the adamj/stateless-http-json-examples branch from 8cf6ea9 to 8dbdfb2 Compare November 18, 2025 15:22
@felixweinberger felixweinberger merged commit fcffa14 into main Nov 20, 2025
38 of 39 checks passed
@felixweinberger felixweinberger deleted the adamj/stateless-http-json-examples branch November 20, 2025 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants