Introduce ServerSession for per-connection state

[koic]

Motivation and Context

The Ruby SDK uses a 1-Server-to-many-sessions model where session-specific state (@client, @logging_message_notification) is stored on the shared Server instance. This causes the last client to connect to overwrite state for all sessions, and requires session_id to be threaded through method signatures for session-scoped notifications.

The Python SDK avoids this by creating a ServerSession per connection that wraps a shared Server. Each session holds its own state and naturally scopes notifications through its own stream.

Changes

• Added MCP::ServerSession class holding per-session state: client info, logging configuration, and a transport reference for session-scoped notification delivery.
• StreamableHTTPTransport#handle_initialization creates a ServerSession per initialize request and stores it in the session hash.
• handle_regular_request routes requests through the session's ServerSession instead of the shared Server directly.
• Server#handle and Server#handle_json accept an optional session: keyword (ServerSession instance).
• Server#init stores client info on the session when available.
• Server#configure_logging_level stores logging config on the session.
• ServerContext and Progress accept a notification_target: which can be either a ServerSession (session-scoped) or a Server (broadcast). No session_id: parameter needed.
• ServerContext#notify_progress and #notify_log_message delegate to the notification_target without session_id threading.
• StdioTransport creates a single ServerSession on open, making the session model transparent across both transports.

Design Decision

This follows the Python SDK's "shared Server + per-connection Session" pattern. The Server holds configuration (tools, prompts, resources, handlers). Each ServerSession holds per-connection state (client info, logging level, stream writer). Notifications from ServerSession go only to that session's stream.

How Has This Been Tested?

All existing tests pass. All conformance tests pass. Added tests verifying:

• Session-scoped log notification is sent only to the originating session.
• Session-scoped progress notification is sent only to the originating session.
• Each session stores its own client info independently.
• Each session stores its own logging level independently.
• StdioTransport#open creates a ServerSession and stores client info on it.

Breaking Change

None for end users.

The public API (Server.new, define_tool,server_context.report_progress, server_context.notify_log_message, etc.) is unchanged. The following internal API changes affect only SDK internals:

• ServerContext.new now requires notification_target: instead of justprogress:.
• Progress.new now takes notification_target: instead of server:.
• Server#handle and Server#handle_json accept an optional session: keyword.

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

[atesgoral]

❤️

[atesgoral]

This is great!