docs: streamable server sample by devcrocod · Pull Request #595 · modelcontextprotocol/kotlin-sdk

devcrocod · 2026-03-09T19:20:53Z

add a simple streamable http server example with auth
update readme: replace quickstart example from sse server to streamable server
add readme files for samples, simple-streamable-server, notebooks

closes #170

How Has This Been Tested?

knit and inspector

Breaking Changes

NaN

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

…rt and tool/resource definitions

…sure consistency in transport and connection details

…consistency

…and readability

Copilot

Pull request overview

Adds a new Streamable HTTP server sample (with optional bearer auth) and refreshes the repository docs/samples documentation to prefer Streamable HTTP over the older SSE quickstart path.

Changes:

Added simple-streamable-server sample showcasing Streamable HTTP, tools/prompts/resources, and logging notifications.
Updated existing sample READMEs and the root README quickstart to use Streamable HTTP.
Added/updated README files for the samples/ index and the notebook sample.

Reviewed changes

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

Show a summary per file

File	Description
samples/weather-stdio-server/README.md	Simplifies and updates weather STDIO server documentation and integration steps.
samples/simple-streamable-server/src/main/kotlin/io/modelcontextprotocol/sample/server/server.kt	Implements the Streamable HTTP Ktor server sample with optional authenticated routing.
samples/simple-streamable-server/src/main/kotlin/io/modelcontextprotocol/sample/server/main.kt	Adds runnable entrypoint with optional `--auth` mode.
samples/simple-streamable-server/settings.gradle.kts	Defines standalone Gradle build settings for the new sample.
samples/simple-streamable-server/gradlew.bat	Adds Windows Gradle wrapper script for the new sample.
samples/simple-streamable-server/gradlew	Adds POSIX Gradle wrapper script for the new sample.
samples/simple-streamable-server/gradle/wrapper/gradle-wrapper.properties	Configures Gradle wrapper distribution for the new sample.
samples/simple-streamable-server/gradle/wrapper/gradle-wrapper.jar	Adds the Gradle wrapper JAR for the new sample.
samples/simple-streamable-server/gradle/libs.versions.toml	Declares dependency versions used by the new sample.
samples/simple-streamable-server/gradle.properties	Enables Gradle performance flags for the new sample build.
samples/simple-streamable-server/build.gradle.kts	Adds dependencies/plugins and application entrypoint for the new sample.
samples/simple-streamable-server/README.md	Documents how to run and use the new Streamable HTTP server sample.
samples/notebooks/README.md	Documents the notebook-based Streamable HTTP client walkthrough.
samples/kotlin-mcp-server/README.md	Repositions SSE modes as backward-compatible and points readers to the new streamable sample.
samples/kotlin-mcp-client/README.md	Simplifies and refreshes client sample documentation and links.
samples/README.md	Adds a samples index/overview table and navigation entrypoints.
README.md	Updates the main quickstart server example to Streamable HTTP and points to the samples overview.

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

codecov-commenter · 2026-03-09T20:37:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

… headers, and enforce required `MCP_AUTH_TOKEN` for authentication.

kpavlov

Looks good in general; however, the example of a streamable server appears awkward.

Please check my comments before merging

kpavlov · 2026-03-10T10:19:35Z

@@ -0,0 +1,28 @@
+package io.modelcontextprotocol.sample.server
+
+import io.ktor.server.cio.CIO


On the JVM target, it's not a good idea to use an exotic server engine that doesn't support HTTP/2. Let's switch to something widely used like Netty or Jetty to showcase a production use case.

This remains an example rather than part of the production code
For example, cors and auth are not configured as they would be in production
I can change the engine, that’s not a problem

kpavlov · 2026-03-10T10:22:37Z

The file has a bit too much information. Let’s keep the server configuration here, and move the Ktor glue code to a different file.

Maybe, but for now I think I'll leave it as is
Later I would refactor part of the code, especially the auth. Then we could either remove it or move it to a separate file

Copilot

Pull request overview

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

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

kpavlov · 2026-03-10T11:32:49Z

        sample:
          - kotlin-mcp-client
          - kotlin-mcp-server
+          - simple-streamable-server


Copilot

Pull request overview

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

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

Copilot · 2026-03-10T11:38:00Z

+    val sessionId = call.request.header(MCP_SESSION_ID_HEADER)
+    if (sessionId != null) {
+        val transport = transports[sessionId]
+        if (transport == null) {
+            call.respond(HttpStatusCode.NotFound, "Session not found")
+        }
+        return transport
+    }


getOrCreateTransport treats an empty mcp-session-id header as a real session ID (it only checks for null), which leads to a misleading 404 "Session not found" instead of a 400 like findTransport does. Consider using the same isNullOrEmpty() validation (and returning 400) or treating blank as absent and creating a new session, to keep behavior consistent across endpoints.

devcrocod added 4 commits March 9, 2026 18:05

Add simple streamable server implementation with authentication suppo…

b93da34

…rt and tool/resource definitions

Update README.md: Adjust section indentation, update examples, and en…

d6bbd93

…sure consistency in transport and connection details

Add sample READMEs for MCP implementations and improve documentation …

0b159bf

…consistency

Remove trailing slashes from links in sample READMEs for consistency …

bbf034d

…and readability

devcrocod requested review from Copilot and e5l March 9, 2026 19:20

Copilot started reviewing on behalf of devcrocod March 9, 2026 19:21 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Simplify Gradle commands in sample READMEs, configure additional CORS…

43ba297

… headers, and enforce required `MCP_AUTH_TOKEN` for authentication.

kpavlov previously approved these changes Mar 10, 2026

View reviewed changes

Switch simple-streamable-server from CIO to Netty server engine

a0526c3

Copilot AI review requested due to automatic review settings March 10, 2026 10:59

devcrocod dismissed kpavlov’s stale review via a0526c3 March 10, 2026 10:59

Copilot started reviewing on behalf of devcrocod March 10, 2026 11:00 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

Comment thread ...les/simple-streamable-server/src/main/kotlin/io/modelcontextprotocol/sample/server/server.kt

Comment thread ...les/simple-streamable-server/src/main/kotlin/io/modelcontextprotocol/sample/server/server.kt Outdated

Comment thread README.md

devcrocod added 2 commits March 10, 2026 12:22

Update README and simple-streamable-server

176ef85

Include simple-streamable-server in GitHub Actions workflows

eba395b

Copilot AI review requested due to automatic review settings March 10, 2026 11:29

Copilot started reviewing on behalf of devcrocod March 10, 2026 11:29 View session

kpavlov reviewed Mar 10, 2026

View reviewed changes

kpavlov approved these changes Mar 10, 2026

View reviewed changes

kpavlov added the samples Sample projects and examples label Mar 10, 2026

Copilot AI reviewed Mar 10, 2026

View reviewed changes

devcrocod merged commit 0b39f57 into main Mar 10, 2026
22 checks passed

devcrocod deleted the devcrocod/streamable-server-sample branch March 10, 2026 11:45

devcrocod mentioned this pull request Apr 1, 2026

Client example - simple streamable #167

Closed

		@@ -0,0 +1,28 @@
		package io.modelcontextprotocol.sample.server

		import io.ktor.server.cio.CIO

Uh oh!

Conversation

devcrocod commented Mar 9, 2026

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Mar 9, 2026

Codecov Report

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kpavlov Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

devcrocod Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

kpavlov Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

devcrocod Mar 10, 2026

Choose a reason for hiding this comment

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!

kpavlov Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants