feat! Add context to server call handlers by rnett · Pull Request #515 · modelcontextprotocol/kotlin-sdk

rnett · 2026-02-12T01:39:12Z

Motivation and Context

Adds a ClientConnection context receiver to server call handlers, which provides access to the client communication channel. This is necessary to allow tools to send notifications, logging, elicitations, etc.

Supersedes #144, discussed in #295.

How Has This Been Tested?

With the added integration test.

Breaking Changes

It breaks binary compatibility and breaks source compatibility for tool handlers that already use this.

If you care a lot about maintaining compatibility, I could add some overloads to ease the transition. But the new methods would likely need to be named differently for resolution.

Future compatibility should be easier to maintain - Context is an interface (with experimental opt-in subclassing), so new fields can be added without breaking compatibility. Different types could also be introduced for different handles without breaking compatibility, as long as they extend ClientConnection.

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

Copilot

Pull request overview

Adds a Context receiver to server request handlers so tool/prompt/resource implementations can access the active ServerSession (e.g., to send notifications).

Changes:

Introduced Context + Handler<T, R> (suspend Context.(T) -> R) to provide session-aware handler APIs
Updated server dispatch to pass session-backed context through tool/prompt/resource handler execution
Added an integration test verifying a tool can send a notification via Context.session

Reviewed changes

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

File	Description
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt	Threads `ServerSession` into handler execution and updates public registration APIs to use `Handler`
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Feature.kt	Introduces `Handler` typealias and updates registered feature handler types
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Context.kt	Adds new public `Context` interface backed by internal `ContextImpl(session)`
integration-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerToolNotificationTest.kt	Validates tools can send notifications using `Context.session`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

Copilot · 2026-02-12T01:41:01Z

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

+        return prompt.run {
+            ContextImpl(session).messageProvider(request)
+        }


The new context-receiver behavior is exercised for tools via the added integration test, but prompts/resources now also rely on ContextImpl(session) for execution. Add integration (or unit) tests covering at least one prompt and one resource handler using session from Context (e.g., sending a notification/log message) to ensure the new receiver wiring works consistently across all handler types.

kpavlov

This change makes perfect sense, and your integration test really shows it off! 👍🏻

However, merging it as it is could cause some issues.

Let's add overloads as context is not always required and to avoid breaking compatibility.
Also, let’s include integration tests for all types of affecter handlers.

devcrocod

At the moment, I don’t quite see the need for a Context and just store session, if we only want to expose a session. We could achieve the same without requiring session.someFun() to be written every time

I’ll also try to find out whether it’s possible to overload functions by lambda. in the past, Kotlin had a special annotation for this. That could help us preserve compatibility.

I’m also concerned about the naming. Since this will be part of the public API, it would be better to use more specific names. Besides potential conflicts, this could also confuse users, as code completion will frequently suggest these symbols

cc: @tiginamaria

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

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

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

kpavlov · 2026-02-12T20:54:01Z

I do not agree, that it is a kind of useless api. This is at least the second community PR: #144

Context is pretty common pattern for server implementation and it provides is a good extension point, also could be used as a place to store some user attributes...
In software, API is never set in stone, unless it is sealed on a chip. We can annotate it @ExperimentalMcpApi.

rnett · 2026-02-12T21:02:38Z

FWIW, the reason I went with Context over just session is that it allows for future changes and extensibility without breaking either source or binary compatibility. Using session would for the current objectives, but if something changed in the future, it could easily cause another breaking change.

rnett · 2026-02-12T21:07:00Z

RE overloads (@kpavlov), do you mean for the registerTool, etc., methods? Because while agree it would be nice, it's not possible for Kotlin to resolve the overloads for a call like:

addTool(tool) {
  // is there a Context receiver or not? - the compiler reports an overload resolution error
}

The only alternative I could think of is using a different name for the new methods, like register instead of add. Thoughts?

devcrocod · 2026-02-13T11:09:49Z

FWIW, the reason I went with Context over just session is that it allows for future changes and extensibility without breaking either source or binary compatibility. Using session would for the current objectives, but if something changed in the future, it could easily cause another breaking change.

Yes, that makes sense. What I meant was to attach extensions to the context in this case, so that the calls are made without a session. Since in the context we have only one variable, all calls will go through the session anyway, so specifying it every time is redundant

devcrocod · 2026-02-13T11:14:01Z

RE overloads (@kpavlov), do you mean for the registerTool, etc., methods? Because while agree it would be nice, it's not possible for Kotlin to resolve the overloads for a call like:

I checked and it looks like there’s only an annotation for overload resolution by return type @OverloadResolutionByLambdaReturnType.
Unfortunately, that won’t work in this case

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

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

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

kotlin-sdk-server/api/kotlin-sdk-server.api

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

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kotlin-sdk-server/api/kotlin-sdk-server.api

rnett · 2026-02-14T22:23:26Z

Yes, that makes sense. What I meant was to attach extensions to the context in this case, so that the calls are made without a session. Since in the context we have only one variable, all calls will go through the session anyway, so specifying it every time is redundant

Ah I see. Personally, I don't find it that verbose, but I've updated the context so that you can call the methods directly on it.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

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

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

...rc/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerHandlerNotificationTest.kt

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

This reverts commit 835d9f3.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

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

The public handler APIs now expose ClientConnection (which is annotated @ExperimentalMcpApi) in their signatures, but Server/addTool/addPrompt/addResource themselves are only annotated with @OptIn at the class level. If the intent is for these new context-receiver handler APIs to be experimental for callers, these public methods should be annotated with @ExperimentalMcpApi (or ClientConnection should be de-experimentalized) so the opt-in requirement is clearly propagated to downstream users.

    /**
     * Registers a single tool. The client can then call this tool.
     *
     * @param tool A [Tool] object describing the tool.
     * @param handler A suspend function that handles executing the tool when called by the client.
     * @throws IllegalStateException If the server does not support tools.
     */
    public fun addTool(tool: Tool, handler: suspend ClientConnection.(CallToolRequest) -> CallToolResult) {
        check(options.capabilities.tools != null) {
            logger.error { "Failed to add tool '${tool.name}': Server does not support tools capability" }
            "Server does not support tools capability. Enable it in ServerOptions."
        }

        toolRegistry.add(RegisteredTool(tool, handler))
    }

integration-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerHandlerNotificationTest.kt:54

These inline comments refer to using the "session" from context, but the new receiver provided to handlers is ClientConnection (and does not directly expose the session). Consider updating the wording to avoid confusion for future readers of the test.

        server.addTool(toolName, "A tool that notifies") { _ ->
            // Use the session from context to send a notification
            sendLoggingMessage(
                LoggingMessageNotification(

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

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

kpavlov

Thank you, @rnett
Looks good, but I have couple of observations.

At Copilot mentioned, marking ClientConnection as experimental api requires OptIn for all addXxxHandler calls. This change will be disruptive for users and we do want to keep the current api shape, so it's not really experimental for the users. Let's remove ExperimentalMcpApi from ClientConnection
Maybe lets make ClientConnection an interface and create ClientConnectionImpl as internal class just for the sake of Dependency Inversion Principle, to have more flexibility in the future.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kpavlov · 2026-02-19T07:10:38Z

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

    }

-    // Start the ServerSession redirection section
+    // Start the ServerSession / ClientConnection redirection section


kpavlov · 2026-02-19T07:11:04Z

...k-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnection.kt

Should we expose it to the handler?

kpavlov · 2026-02-19T07:11:09Z

...k-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnection.kt

Should we expose it to the handler?

kpavlov · 2026-02-19T07:11:49Z

...k-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnection.kt

Should we expose it to the handler?

kpavlov · 2026-02-19T07:12:20Z

...k-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnection.kt

Should we expose such low-level API to the handler?

kpavlov

I removed some methods from ClientConnection.kt, updated tests

but overall LGTM.
@devcrocod , WDYT

…ty from `ClientConnection` - Removed `serverCapabilities` and `clientCapabilities` properties, along with redundant `onClose`, `request`, and logging-level handling methods. - Simplified `request` and `notification` methods for improved clarity. - Updated corresponding tests to reflect the removed functionality.

…ing for notifications - Added tests to ensure `sendLoggingMessage` and notifications respect the set logging level and properly filter messages below the threshold. - Updated assertions to use `shouldBe` and collection matchers for clarity.

…ication handling in tests - Updated `ClientConnection` to simplify methods by consolidating parameters and removing unused logic. - Replaced `Notification` with `ServerNotification` for stronger typing. - Removed client version and message acceptance logic from the interface. - Simplified test cases to use `shouldBe` and removed redundant assertions for improved clarity and maintainability.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

…tekt baselines, and enhance `AbstractServerFeaturesTest` - Made `clientConnection` and `serverCapabilities` private to restrict access scope. - Simplified detekt baselines by removing outdated or unneeded configurations. - Enhanced `AbstractServerFeaturesTest` by adding `addTool` helper for streamlined test setup.

kpavlov

LGTM

devcrocod

let’s merge it

Copilot AI review requested due to automatic review settings February 12, 2026 01:39

rnett mentioned this pull request Feb 12, 2026

Server should be accissible to tool handlers #295

Open

Copilot AI reviewed Feb 12, 2026

View reviewed changes

kpavlov requested changes Feb 12, 2026

View reviewed changes

kpavlov requested review from devcrocod and tiginamaria February 12, 2026 13:41

devcrocod reviewed Feb 12, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings February 14, 2026 22:04

Copilot started reviewing on behalf of rnett February 14, 2026 22:04 View session

Copilot AI reviewed Feb 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings February 14, 2026 22:16

Copilot started reviewing on behalf of rnett February 14, 2026 22:17 View session

Copilot AI reviewed Feb 14, 2026

View reviewed changes

kotlin-sdk-server/api/kotlin-sdk-server.api Outdated Show resolved Hide resolved

rnett requested review from Copilot, devcrocod and kpavlov February 14, 2026 22:30

Copilot started reviewing on behalf of rnett February 14, 2026 22:30 View session

Copilot AI reviewed Feb 14, 2026

View reviewed changes

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

Copilot AI review requested due to automatic review settings February 17, 2026 08:25

kpavlov force-pushed the rnett/add-server-context branch from 164c935 to dbbe95b Compare February 17, 2026 08:25

Copilot AI reviewed Feb 17, 2026

View reviewed changes

kpavlov added the enhancement New feature or request label Feb 17, 2026

kpavlov reviewed Feb 17, 2026

View reviewed changes

...rc/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerHandlerNotificationTest.kt Show resolved Hide resolved

Copilot AI reviewed Feb 19, 2026

View reviewed changes

rnett added 2 commits February 18, 2026 20:58

Remove unnecessary suppression

835d9f3

Merge branch 'main' into rnett/add-server-context

fa5c363

Copilot AI review requested due to automatic review settings February 19, 2026 04:59

Copilot started reviewing on behalf of rnett February 19, 2026 05:00 View session

Revert "Remove unnecessary suppression"

3461ae9

This reverts commit 835d9f3.

Copilot AI reviewed Feb 19, 2026

View reviewed changes

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

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

kpavlov reviewed Feb 19, 2026

View reviewed changes

rnett added 3 commits February 18, 2026 21:23

Add test coverage for ClientConnection

1aff271

Remove experimental annotation

0ef73da

Extract ClientConnection interface

31ce01a

Copilot AI review requested due to automatic review settings February 19, 2026 05:38

Copilot started reviewing on behalf of rnett February 19, 2026 05:39 View session

rnett requested review from devcrocod and kpavlov February 19, 2026 05:39

Copilot AI reviewed Feb 19, 2026

View reviewed changes

kpavlov reviewed Feb 19, 2026

View reviewed changes

kpavlov self-requested a review February 19, 2026 07:19

kpavlov added 3 commits February 19, 2026 10:08

Copilot AI review requested due to automatic review settings February 19, 2026 09:51

Copilot AI reviewed Feb 19, 2026

View reviewed changes

kpavlov changed the title ~~Add context to server call handlers~~ feat! Add context to server call handlers Feb 19, 2026

kpavlov added the breaking Breaking changes 👧🏠🔥 label Feb 19, 2026

kpavlov approved these changes Feb 19, 2026

View reviewed changes

kpavlov requested a review from e5l February 19, 2026 10:19

devcrocod approved these changes Feb 19, 2026

View reviewed changes

Conversation

rnett commented Feb 12, 2026 • 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kpavlov commented Feb 12, 2026

Uh oh!

rnett commented Feb 12, 2026

Uh oh!

rnett commented Feb 12, 2026

Uh oh!

devcrocod commented Feb 13, 2026

Uh oh!

devcrocod commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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

Uh oh!

Uh oh!

rnett commented Feb 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

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

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

rnett commented Feb 12, 2026 •

edited by kpavlov

Loading

kpavlov left a comment •

edited

Loading

kpavlov left a comment •

edited

Loading