Skip to content

Add ISessionMigrationHandler#1270

Open
MackinnonBuck wants to merge 5 commits intomainfrom
mbuck/session-migration-handler
Open

Add ISessionMigrationHandler#1270
MackinnonBuck wants to merge 5 commits intomainfrom
mbuck/session-migration-handler

Conversation

@MackinnonBuck
Copy link
Collaborator

Summary

Adds ISessionMigrationHandler to enable session migration across horizontally-scaled server instances (#1155), and rejects non-initialize POST requests without a session ID in stateful mode (#1000).

Description

When MCP servers are deployed behind a load balancer, a client's session may land on a server instance that doesn't recognize the session ID. This PR introduces an opt-in ISessionMigrationHandler interface (registered via DI) that allows servers to persist session init data and restore sessions on demand.

Session migration flow:

  1. After a successful initialize handshake, OnSessionInitializedAsync is called so the server can persist the InitializeRequestParams (e.g., to Redis or a database).
  2. When a request arrives with an unrecognized session ID, AllowSessionMigrationAsync is called. If it returns the original InitializeRequestParams, a new local session is created with that client state pre-populated; no re-initialization required from the client's perspective.

Reject sessionless non-initialize requests in stateful mode

In stateful mode, POST requests without a session ID are now rejected with 400 unless the message is an initialize request. This required reordering HandlePostRequestAsync to read the JSON-RPC message before deciding on session creation. Stateless mode is unaffected.

Notable design decisions:

  • ISessionMigrationHandler lives in ModelContextProtocol.Core (not AspNetCore).
  • The handler is set as a typed property on StreamableHttpServerTransport (similar to EventStreamStore), and HandleInitRequestAsync is public so migration can call it directly without going through a full POST flow.
  • KnownClientCapabilities was added to McpServerOptions, following the existing KnownClientInfo pattern.

Fixes #1155
Fixes #1000

@jeffhandley jeffhandley added the breaking-change This issue or PR introduces a breaking change label Feb 19, 2026
@jeffhandley
Copy link
Collaborator

@copilot Summarize the breaking changes into API and behavioral change bullets please

Copy link
Contributor

Copilot AI commented Feb 19, 2026

@jeffhandley I've opened a new pull request, #1312, to work on those changes. Once the pull request is ready, I'll request review from you.

@jeffhandley jeffhandley added this to the Stable public API milestone Feb 19, 2026
@jeffhandley
Copy link
Collaborator

Status: @halter73 is going to take one more PR review pass over this. We plan to merge it in for 1.0.0, and it will resolve #1000.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-change This issue or PR introduces a breaking change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow HybridCache for session storage Don't create sessions for requests without a sessionId

4 participants

Comments