modelcontextprotocol / modelcontextprotocol/kotlin-sdk

refactor: Decouple MCP JSON serialization from global ContentNegotiation configuration

Open
#668 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api enhancement P3 ready for work refactoring
Dominant language
Kotlin
Stars
1.5k
Forks
248
Avg merge
1d 20h
Merged PRs (30d)
23

Description

Problem

Caused by #664.

MCP requires specific kotlinx.serialization.json.Json settings (explicitNulls = false, encodeDefaults = true, classDiscriminatorMode = NONE), currently bundled as McpJson. The Ktor server must install ContentNegotiation with this exact configuration:

install(ContentNegotiation) {
    json(McpJson)
}

This creates two problems:

  1. Easy to forget. Users who omit McpJson get silent serialization failures at runtime (e.g., explicit null fields in JSON-RPC responses). Partially addressed by auto-installation in #665.

  2. Conflicts with application-wide JSON configuration. Users may need different Json settings for non-MCP routes (e.g., encodeDefaults = false, prettyPrint = true, custom naming strategies). Because Ktor's ContentNegotiation applies a single Json instance globally, there is no way to use one configuration for MCP endpoints and another for the rest of the application.

Proposal

Inline the required serialization behavior into MCP schema classes (DTOs) using kotlinx.serialization annotations, so they serialize correctly regardless of the global Json configuration.

Class-level settings override global settings, so users would be free to configure ContentNegotiation however they need:

install(ContentNegotiation) {                                                                                                                                                                                  
    json() // any configuration — MCP classes carry their own settings
}                                                                                                                                                                                                                

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating McpJson, the MCP schema classes, and the ContentNegotiation setup. Check how the schema DTOs serialize under different global Json configurations, then verify that MCP-required settings remain effective without installing McpJson globally. Done means MCP endpoints retain the required JSON behavior while non-MCP routes can use their own configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
api, backend-api-design
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.