Skip to content

Conversation

Bumshakalaka
Copy link

Changed the status code from BAD_REQUEST to NOT_FOUND and added MCP_SESSION_ID_HEADER with Mcp-Session-Id

Motivation and Context

Current behavior of HTTP Session Manager is not align with MCP specification.
https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management

  1. The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found.

In my opinion the else case, in the StreamableHTTP Session Manager for stateful events, handles request with old/invalid Mcp-Session-Idafter unintentional session terminate (server restart). In that case NOT_FOUND status MUST be returned, not BAD_REQUEST.

How Has This Been Tested?

Locally with Cursor AI.
Currently Cursor 1.6.x does not start new session after such response, see: https://forum.cursor.com/t/mcp-client-wrong-handling-of-http-not-found-in-session-management-stateful-mcp-server/134781

Breaking Changes

Probably, depends on MCP client logic implementation.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

…HTTPSessionManager

Changed the status code from BAD_REQUEST to NOT_FOUND and added MCP_SESSION_ID_HEADER to the response headers if available. This behaviour is align with MCP spec https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management
@Bumshakalaka Bumshakalaka requested review from a team and Kludex September 24, 2025 13:27
@felixweinberger felixweinberger added bug Something isn't working breaking change Will break existing deployments when updated without changes improves spec compliance When a change improves ability of SDK users to comply with spec definition v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes labels Sep 26, 2025
@felixweinberger
Copy link
Contributor

I believe this is a legitimate improvement to spec compliance but represents a breaking change - I'm marking this for a future v2 and converting this to a draft for now to remove it from the immediate review queue.

@felixweinberger felixweinberger marked this pull request as draft September 30, 2025 11:24
@felixweinberger felixweinberger added this to the Python SDK v2.0 milestone Sep 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking change Will break existing deployments when updated without changes bug Something isn't working improves spec compliance When a change improves ability of SDK users to comply with spec definition v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants