Introduce server sessions #198

tiginamaria · 2025-07-25T17:30:42Z

Introduce a ServerSession to manage multiple connections to the mcp server. Protocall logic of the Server was moved to ServerSession, while MCP resources logic remained in Server

Motivation and Context

Fix the multiple connection issues reported for sse transport
Avoid server duplications during configurations, now every connection creates a session, but the server stays single

How Has This Been Tested?

Added SseIntegrationTest and WebSocketIntegrationTest integration tests to check connection with single and multiple clients

Breaking Changes

This change caused several depreciations:

The Server -> Protocol inheritance (which caused single connection issue) should be removed in future releases, now, all the methods inherited from Protocall marked as Deprecated with a Warning
Websocket ktor server initialization changes in order not to create server instance per connection

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

tiginamaria · 2025-07-25T17:34:26Z

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/WebSocketMcpKtorServerExtensions.kt

+    var session: ServerSession? = null
+    try {
+        session = server.connectSession(transport)
+        awaitCancellation()


Finishes without await in tests, not sure if it's a right approach to fix it, please take a look here! Really need some help here

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

devcrocod

The PR looks good to me overall!

Please take a look at my comments.
My main concern is about the behavior of the Server
It would also be great to update the existing samples and the README accordingly

api/kotlin-sdk.api

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

Copilot

Pull Request Overview

This PR introduces server sessions to manage multiple connections to MCP servers. The implementation moves protocol logic from the Server class to a new ServerSession class, allowing the server to handle multiple simultaneous connections while maintaining a single server instance.

Introduces ServerSession class for managing individual client connections
Moves protocol-level functionality from Server to ServerSession
Updates WebSocket and SSE transport implementations to support multiple sessions
Adds comprehensive integration tests for both single and multiple connection scenarios

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
SseIntegrationTest.kt	New integration test verifying SSE transport with single and multiple client connections
WebSocketIntegrationTest.kt	New integration test verifying WebSocket transport with single and multiple client connections
SseTransportTest.kt	Updates to use new `SseTransportManager` instead of direct transport map
WebSocketMcpTransport.kt	Adds debug logging for WebSocket transport operations
Protocol.kt	Refactors logger variable naming for consistency
WebSocketMcpServerTransport.kt	Adds debug logging for session header validation
WebSocketMcpKtorServerExtensions.kt	Major refactor to support session-based architecture with new API and deprecation warnings
ServerSession.kt	New class implementing session-specific protocol handling moved from Server
Server.kt	Refactored to manage multiple sessions while maintaining resource management
SSEServerTransport.kt	Removes unused import
KtorServer.kt	Introduces `SseTransportManager` for better session management
WebSocketMcpKtorClientExtensions.kt	Adds debug logging for client connection process
WebSocketClientTransport.kt	Adds debug logging for session initialization
SSEClientTransport.kt	Adds debug logging for message sending and endpoint connection
Client.kt	Improves error handling during connection initialization
kotlin-sdk.api	Updates API surface to include new classes and deprecation warnings

Comments suppressed due to low confidence (1)

src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt:37

The test method name 'client should be able to connect to websocket server 2' is unclear. The '2' suffix doesn't indicate what distinguishes this test from others. Consider renaming to something more descriptive like 'client establishes websocket connection successfully'.

    fun `client should be able to connect to websocket server 2`() = runTest {

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/SseIntegrationTest.kt

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/WebSocketMcpKtorServerExtensions.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

e5l

Hey @tiginamaria, thank you for the PR. Could you add a sample as a docs page illustrating what the difference will be between kotlin and the original TypeScript API?

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt

devcrocod

lgtm!

kpavlov

Thank you, @tiginamaria, @devcrocod. Callback chaining implementation is very simple and it can be improved in a separate PR along with the tests.

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

...sdk-test/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/SseTransportTest.kt

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/WebSocketMcpKtorClientExtensions.kt

...ore/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/WebSocketMcpTransport.kt

...-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt

devcrocod · 2025-08-26T11:17:56Z

@tiginamaria
please check tests failed:

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.client should be able to connect to sse server[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.single sse connection[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.multiple sse connections[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.client should be able to connect to websocket server 2[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.single websocket connection[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.multiple websocket connections[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

runBlocking is not supported for wasm

devcrocod · 2025-08-26T11:52:08Z

I found the problem: these tests use stop for the Ktor server, but it should be stopSuspend

...lin/io/modelcontextprotocol/kotlin/sdk/integration/kotlin/AbstractResourceIntegrationTest.kt

kpavlov

Thank you, @tiginamaria
I identified several areas where the cleanup process could be improved

kpavlov · 2025-09-18T16:56:09Z

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

 private val logger = KotlinLogging.logger {}

+internal class SseTransportManager(transports: Map<String, SseServerTransport> = emptyMap()) {
+    private val transports: AtomicRef<PersistentMap<String, SseServerTransport>> = atomic(transports.toPersistentMap())


We have decided to use ConcurrentMaps from ktor, right?

kpavlov · 2025-09-18T17:06:04Z

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

-        logger.debug { "Initializing MCP server with capabilities: $capabilities" }
+    public suspend fun close() {
+        logger.debug { "Closing MCP server" }
+        sessions.value.forEach { it.close() }


Let's also clear sessions afterwards. Also, let's add try-catch around session.close() to make sure all resources are released. Let's also add unit test about it: verify that method close() is called for all sessions

kpavlov · 2025-09-18T17:22:02Z

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

 */
-public open class Server(private val serverInfo: Implementation, options: ServerOptions) : Protocol(options) {
+public open class Server(private val serverInfo: Implementation, private val options: ServerOptions) {
+    private val sessions = atomic(persistentListOf<ServerSession>())


When one session is closed, it should be removed from the collection. It might be better to use ConcurrentMap<SessionId, ServerSession>. But I failed to find where it is happening...

kpavlov · 2025-09-18T17:27:23Z

...t/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/SseIntegrationTest.kt

-        val serverEngine = initServer()
+    fun `client should be able to connect to sse server`() = runTest(timeout = 5.seconds) {
+        var server: EmbeddedServer<CIOApplicationEngine, CIOApplicationEngine.Configuration>? = null
+        var client: Client? = null


Suggested change

var client: Client? = null

lateinit var client: Client

?

tiginamaria requested a review from devcrocod July 25, 2025 17:31

tiginamaria commented Jul 25, 2025

View reviewed changes

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt Outdated Show resolved Hide resolved

tiginamaria force-pushed the tigina/server-session branch from f33add5 to 0265956 Compare July 25, 2025 20:48

devcrocod requested changes Jul 27, 2025

View reviewed changes

devcrocod requested review from e5l, sdubov and Copilot July 27, 2025 15:48

Copilot AI reviewed Jul 27, 2025

View reviewed changes

e5l requested changes Jul 28, 2025

View reviewed changes

devcrocod mentioned this pull request Jul 30, 2025

FEAT: Support almost all Tier 1, 2 and 3 Kotlin targets #151

Merged

9 tasks

tiginamaria force-pushed the tigina/server-session branch from 560c13f to f9f1a15 Compare August 4, 2025 15:58

devcrocod mentioned this pull request Aug 7, 2025

Why is Kotlin SDK always left behind? #218

Open

tiginamaria force-pushed the tigina/server-session branch from fcf25b6 to 18a4174 Compare August 20, 2025 09:33

tiginamaria requested review from devcrocod and e5l August 21, 2025 12:22

tiginamaria marked this pull request as ready for review August 25, 2025 14:26

devcrocod previously approved these changes Aug 25, 2025

View reviewed changes

devcrocod force-pushed the tigina/server-session branch from e26cea1 to 239fc97 Compare August 25, 2025 18:27

kpavlov previously approved these changes Aug 26, 2025

View reviewed changes

tiginamaria dismissed devcrocod’s stale review via b66f0bf September 9, 2025 13:53

tiginamaria force-pushed the tigina/server-session branch from b66f0bf to c609a01 Compare September 9, 2025 13:56

devcrocod self-requested a review September 9, 2025 16:04

devcrocod force-pushed the tigina/server-session branch from c622cfe to 6b3dcc4 Compare September 10, 2025 09:31

tiginamaria dismissed kpavlov’s stale review via 6b3dcc4 September 10, 2025 13:10

tiginamaria force-pushed the tigina/server-session branch from bb9d9bd to 4ec36af Compare September 18, 2025 09:54

tiginamaria added 2 commits September 18, 2025 11:54

Introduce server session

e0b1172

Fix websocket ktor server implementation, add test and logs

db043a3

tiginamaria and others added 14 commits September 18, 2025 11:54

Fix imports

fcb13e2

Change api

ea26789

Changes after rebase

ed0718d

Remove Protocol from Server

ca3293a

Fix compilation

89b0c63

Fix linter, add enums instead of strings in capabilities assertion

073f47a

Dump api

629b5ef

Fix tests

ff4c1c9

Fix tests

d64f6d5

Stop -> StopSuspend

a7fb461

Fix ktlint

ef1cf92

Fix tests

1a7ea4e

update api: remove ResourceReference

b16f447

fix formatting

b19353d

tiginamaria force-pushed the tigina/server-session branch from 4ec36af to b19353d Compare September 18, 2025 09:55

tiginamaria commented Sep 18, 2025

View reviewed changes

...lin/io/modelcontextprotocol/kotlin/sdk/integration/kotlin/AbstractResourceIntegrationTest.kt Outdated Show resolved Hide resolved

tiginamaria and others added 4 commits September 18, 2025 15:10

Fix tests

be77ed1

Update examples

e33bf0e

Merge branch 'main' into tigina/server-session

07fa2d4

Fix api

9d5cc91

tiginamaria requested a review from kpavlov September 18, 2025 14:41

kpavlov reviewed Sep 18, 2025

View reviewed changes

kpavlov added the enhancement New feature or request label Sep 18, 2025

kpavlov reviewed Sep 18, 2025

View reviewed changes

Introduce server sessions #198

Are you sure you want to change the base?

Introduce server sessions #198

Conversation

tiginamaria commented Jul 25, 2025 • edited by kpavlov Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

tiginamaria Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devcrocod commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devcrocod commented Aug 26, 2025

Uh oh!

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 18, 2025

Choose a reason for hiding this comment

tiginamaria commented Jul 25, 2025 •

edited by kpavlov

Loading

tiginamaria Jul 25, 2025 •

edited

Loading

devcrocod commented Aug 26, 2025 •

edited

Loading