feat(server): auto-install ContentNegotiation with McpJson (#664) by kpavlov · Pull Request #665 · modelcontextprotocol/kotlin-sdk

kpavlov · 2026-04-01T13:44:57Z

Users currently must manually install(ContentNegotiation) { json(McpJson) } before calling mcp(),
mcpStreamableHttp(), or mcpStatelessStreamableHttp(). Forgetting this or using the default json()
instead of json(McpJson) causes silent serialization failures at runtime (e.g., explicit null fields in JSON-RPC
responses). This PR makes the SDK install it automatically.

Fixes #664

Changes

Core feature — mcp(), mcpStreamableHttp(), and mcpStatelessStreamableHttp() now auto-install ContentNegotiation configured with McpJson. If the user already installed ContentNegotiation, a warning is logged instead of crashing with DuplicatePluginException.
KtorServerHelpers.kt (new) — installMcpContentNegotiation() internal helper with pluginOrNull guard and warning
KtorServer.kt — calls the helper from all three entry points
build.gradle.kts — adds ktor-server-content-negotiation and ktor-serialization as implementation deps to kotlin-sdk-server
Removed manual installs from ConformanceServer.kt and AbstractStreamableHttpIntegrationTest.kt.
Test infrastructure — replaced slf4j-simple with Logback and use ListAppender (LogCapture utility) for deterministic log assertion. Added logback-test.xml matching previous log levels.
StreamableHttpServerConfigurationTest.kt (new) — verifies the warning for all three entry points: mcpStreamableHttp, mcpStatelessStreamableHttp, and mcp (SSE).
README.md — removed manual ContentNegotiation boilerplate from examples, documented automatic installation, added CORS configuration snippet for browser-based clients.
CI — added ktlintCheck to the Linux build matrix job.

How Has This Been Tested?

Unit/integration tests. Conformance tests updated

Breaking Changes

No

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

mcp(), mcpStreamableHttp(), and mcpStatelessStreamableHttp() now install ContentNegotiation configured with McpJson automatically, removing the need for users to do it manually. If ContentNegotiation was already installed by user code, a warning is logged instead of crashing with DuplicatePluginException.

- adjust formatting in StreamableHttpClientTest for consistency - ci: run ktlint first and fail fast on CI

…rationTest

- Replaced captureStderr with a Logback ListAppender-based LogCapture utility - Swapped slf4j-simple for logback-classic in kotlin-sdk-server's test dependencies - Added logback-test.xml (matching the previous simplelogger.properties levels) - Tests now assert directly on captured log events instead of relying on stderr output

codecov-commenter · 2026-04-01T14:46:02Z

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!

devcrocod

Thank you for the PR, this indeed needs to be fixed

However, it is still unclear to me what the user is supposed to do if they want to provide their own JSON configuration
for example, enable pretty printing or set other options in addition to explicitNulls and the rest

Also, in addition to the comments I already left, the AI review pointed out that KotlinTestBase was missed as well, and it also uses install(ContentNegotiation)

devcrocod · 2026-04-01T15:56:46Z

.github/workflows/build.yml

          - os: ubuntu-latest
            job-name: "Linux Tests"
-            gradle-tasks: "build"
+            gradle-tasks: "ktlintCheck build"


How is it related to PR?
and ktlintCheck runs with check, which means it's already included in build task

build runs check after running tests. Build should fail earlier if it can not be merged.

build runs check after running tests. Build should fail earlier if it can not be merged.

That's not correct. test is part of check

ktlintCheck doesn't depend on the tests. When running build, the tests and ktlintCheck are executed in parallel. So it is not entirely clear in which scenario "Build should fail earlier" would actually make the build fail faster

devcrocod · 2026-04-01T15:57:58Z

gradle/libs.versions.toml

 mokksy = { group = "dev.mokksy", name = "mokksy", version.ref = "mokksy" }
 netty-bom = { group = "io.netty", name = "netty-bom", version.ref = "netty" }
 slf4j-simple = { group = "org.slf4j", name = "slf4j-simple", version.ref = "slf4j" }
+logback-classic = { group = "ch.qos.logback", name = "logback-classic", version.ref = "logback" }


Why do we need another logger?

For testing, please check the tests.

devcrocod · 2026-04-01T16:00:48Z

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

+                "Remove your install(ContentNegotiation) { … } block and let " +
+                "mcp() / mcpStreamableHttp() / mcpStatelessStreamableHttp() configure it automatically."


To be honest, that’s a strange suggestion for me

devcrocod · 2026-04-01T16:02:38Z

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

+ * Automatically installs [ContentNegotiation][io.ktor.server.plugins.contentnegotiation.ContentNegotiation]
+ * with [McpJson][io.modelcontextprotocol.kotlin.sdk.types.McpJson] and [SSE].


Why hasn’t kdoc been updated for the other methods?

devcrocod · 2026-04-01T16:06:23Z

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

    configuration: StreamableHttpServerTransport.Configuration,
    block: RoutingContext.() -> Server,
 ) {
+    installMcpContentNegotiation()


If the user is configured to use multiple extensions, they will see a warning saying that ContentNegotiation is already installed

?
I mean our extensions: mcp and mcpStreamable

In this case, we must store an application attribute and make installMcpContentNegotiation() completely idempotent. Done

devcrocod · 2026-04-01T16:19:21Z

kotlin-sdk-server/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/LogCapture.kt

+internal class LogCapture(loggerName: String) : AutoCloseable {
+    private val logger: Logger = LoggerFactory.getLogger(loggerName) as Logger
+    private val appender: ListAppender<ILoggingEvent> = ListAppender()
+
+    init {
+        appender.start()
+        logger.addAppender(appender)
+    }
+
+    val messages: List<String>
+        get() = appender.list.map { it.formattedMessage }
+
+    override fun close() {
+        logger.detachAppender(appender)
+        appender.stop()
+    }
+}


Wouldn't it be enough to just verify that no DuplicatePluginException is thrown?
The existing integration tests already prove that this works, since they did not break after the manual installation of ContentNegotiation was removed

Verifying the exact log output does not seem quite right because it may change at any moment. On top of that, it adds another dependency, extra configuration, and new tests that verify log output. It feels unnecessary

DuplicatePluginException should not be thrown, otherwise it will break current users. Also, users should still be able to install their own ContentNegotiation configuration. That's why it is warniong, not an error.

The log message that should be verified, this is expected behavior and to verify. When extra dependency and configuration is needed - it is needed

It's the log message that should be verified. When extra dependency and configuration is needed - it is needed

Why is that? Your comment doesn’t make it clear

devcrocod · 2026-04-01T16:20:05Z

README.md

+**CORS for browser-based clients (e.g. MCP Inspector):** if you connect from a browser-based
+client you need to install the Ktor CORS plugin so that MCP-specific headers are allowed and exposed:
+
+```kotlin
+install(CORS) {
+    anyHost() // restrict to specific origins in production
+    allowMethod(HttpMethod.Options)
+    allowMethod(HttpMethod.Get)
+    allowMethod(HttpMethod.Post)
+    allowMethod(HttpMethod.Delete)
+    allowNonSimpleContentTypes = true
+    allowHeader("Mcp-Session-Id")
+    allowHeader("Mcp-Protocol-Version")
+    exposeHeader("Mcp-Session-Id")
+    exposeHeader("Mcp-Protocol-Version")
+}
+```
+


How is it related to PR?

This is a finding from the troubleshooting session. The MCP Inspector does not function with the default configuration without this.

Didn't you suggest not mixing unrelated changes in the same PR?

I agree, but this often occurs in this project. This note is related to the user’s issue. So "boy scout's rule" apply.

devcrocod · 2026-04-01T16:21:41Z

README.md

+    // mcpStreamableHttp() automatically installs ContentNegotiation with McpJson.
+    // Do NOT install ContentNegotiation yourself — the SDK handles it.


Why need this comment in the code snippet?

Use Application.attributes to track whether the SDK has already handled ContentNegotiation installation. Subsequent calls return immediately without re-installing or logging spurious warnings. Also softens the warning message for user-pre-installed ContentNegotiation to suggest ensuring json(McpJson) is included rather than demanding removal, and adds auto-install KDoc to mcpStreamableHttp/mcpStatelessStreamableHttp. Remove comment in code snippet in README.md

e5l

Two issues found — see inline comments.

e5l · 2026-04-02T07:12:00Z

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

+                "Ensure your ContentNegotiation configuration includes json(McpJson)."
+        }
+    } else {
+        install(ContentNegotiation) {


When the user has pre-installed ContentNegotiation with wrong config (e.g. default json() instead of json(McpJson)), this logs a warning but doesn't actually fix anything — the runtime serialization failures still happen silently.

This means the most dangerous case (user installed CN incorrectly) isn't addressed. Consider either:

Registering McpJson as an additional converter even when CN is already installed

Failing fast with an exception instead of a warning

As written, the fix only helps users who forgot to install CN entirely, not those who installed it with the wrong config.

e5l · 2026-04-02T07:12:02Z

kotlin-sdk-server/build.gradle.kts

                api(libs.ktor.server.core)
                api(libs.ktor.server.sse)
+                implementation(libs.ktor.server.content.negotiation)
                implementation(libs.ktor.server.websockets)


ktor-serialization should already come in transitively via ktor-server-content-negotiation. Is there a specific multiplatform reason this is needed as a direct dependency? If not, it can be removed.

Unfortunately, both ktor-server-content-negotiation and ktor-serialization are required

e5l

agreed to fix it as separate pr

kpavlov · 2026-04-02T08:18:20Z

Added follow-up issue #668

kpavlov added documentation Improvements or additions to documentation bugfix internal-users Raised by internal users labels Apr 1, 2026

kpavlov force-pushed the kpavlov/664-json-config branch from 38b5ee0 to 29c5946 Compare April 1, 2026 14:11

kpavlov added 4 commits April 1, 2026 17:31

fix(test): adjust formatting in StreamableHttpClientTest for consistency

0dcd79c

- adjust formatting in StreamableHttpClientTest for consistency - ci: run ktlint first and fail fast on CI

fix(test): remove redundant assertions in StreamableHttpServerConfigu…

275896a

…rationTest

kpavlov force-pushed the kpavlov/664-json-config branch from 27849ca to 787211b Compare April 1, 2026 14:31

revert ClientTest

0a1a2c4

kpavlov marked this pull request as ready for review April 1, 2026 15:17

kpavlov requested review from devcrocod and e5l and removed request for e5l April 1, 2026 15:17

devcrocod reviewed Apr 1, 2026

View reviewed changes

e5l requested changes Apr 2, 2026

View reviewed changes

e5l reviewed Apr 2, 2026

View reviewed changes

e5l self-requested a review April 2, 2026 08:00

e5l approved these changes Apr 2, 2026

View reviewed changes

kpavlov merged commit 3617ce4 into main Apr 2, 2026
20 checks passed

kpavlov deleted the kpavlov/664-json-config branch April 2, 2026 08:01

kpavlov mentioned this pull request Apr 2, 2026

refactor: Decouple MCP JSON serialization from global ContentNegotiation configuration #668

Open

kpavlov added this to the 0.11 milestone Apr 2, 2026

		"Remove your install(ContentNegotiation) { … } block and let " +
		"mcp() / mcpStreamableHttp() / mcpStatelessStreamableHttp() configure it automatically."

		* Automatically installs [ContentNegotiation][io.ktor.server.plugins.contentnegotiation.ContentNegotiation]
		* with [McpJson][io.modelcontextprotocol.kotlin.sdk.types.McpJson] and [SSE].

		// mcpStreamableHttp() automatically installs ContentNegotiation with McpJson.
		// Do NOT install ContentNegotiation yourself — the SDK handles it.

Conversation

kpavlov commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

codecov-commenter commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kpavlov Apr 1, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kpavlov Apr 1, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

kpavlov Apr 1, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kpavlov Apr 1, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov commented Apr 1, 2026 •

edited

Loading

codecov-commenter commented Apr 1, 2026 •

edited

Loading

kpavlov Apr 1, 2026 •

edited

Loading

kpavlov Apr 1, 2026 •

edited

Loading

kpavlov Apr 1, 2026 •

edited

Loading

kpavlov Apr 1, 2026 •

edited

Loading