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 · 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

?

kpavlov

Thank you! This PR looks good and useful to me. Let's get it merged and address any concerns in follow-up PRs

kpavlov · 2025-09-29T07:10:04Z

Merging with the #297 in mind

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 Copilot, e5l and sdubov 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 2 times, most recently 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

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

kpavlov reviewed Sep 18, 2025

View reviewed changes

kpavlov force-pushed the tigina/server-session branch from 9d5cc91 to 7c6e122 Compare September 26, 2025 13:27

kpavlov approved these changes Sep 26, 2025

View reviewed changes

e5l approved these changes Sep 26, 2025

View reviewed changes

tiginamaria and others added 19 commits September 29, 2025 09:47

Introduce server session

6fcc82f

Fix websocket ktor server implementation, add test and logs

80716cd

Fix imports

b9014d9

Change api

708e154

Changes after rebase

5152ab6

Remove Protocol from Server

9b03ea6

Fix compilation

4a1631d

Fix linter, add enums instead of strings in capabilities assertion

fde886c

Dump api

901eb94

Fix tests

65c187f

Fix tests

dbaf7c5

Stop -> StopSuspend

46c8567

Fix ktlint

1403db9

Fix tests

6d5f649

update api: remove ResourceReference

282b1bd

fix formatting

efbe8e8

Fix tests

9268608

Update examples

dc98708

Fix api

5ba48b0

kpavlov force-pushed the tigina/server-session branch from 7c6e122 to 5ba48b0 Compare September 29, 2025 06:47

kpavlov mentioned this pull request Sep 29, 2025

ServerSessions follow-up #297

Open

kpavlov merged commit d868136 into main Sep 29, 2025
6 checks passed

kpavlov deleted the tigina/server-session branch September 29, 2025 07:10

devcrocod mentioned this pull request Sep 29, 2025

Reusable server "specs" - don't re-create the server from scratch for each transport #296

Open

Introduce server sessions #198

Introduce server sessions #198

Uh oh!

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 Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov commented Sep 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

tiginamaria commented Jul 25, 2025 •

edited by kpavlov

Loading

tiginamaria Jul 25, 2025 •

edited

Loading

devcrocod commented Aug 26, 2025 •

edited

Loading