Module kotlin-sdk-core

February 6, 2026 · View on GitHub

kotlin-sdk-core is the foundation of the MCP Kotlin SDK. It contains protocol message types, JSON handling, and transport abstractions used by both client and server modules. No platform-specific code lives here; everything is designed for Kotlin Multiplatform with explicit API mode enabled.

What the module provides

  • Protocol model: Complete MCP data classes for requests, results, notifications, capabilities, tools, prompts, resources, logging, completion, sampling, elicitation, and roots. DSL helpers (*.dsl.kt) let you build messages fluently without repeating boilerplate.
  • JSON utilities: A shared McpJson configuration (kotlinx.serialization) with MCP-friendly settings (ignore unknown keys, no class discriminator). Helpers for converting maps to JsonElement, EmptyJsonObject, and encoding/decoding JSON-RPC envelopes.
  • Transport abstractions: Transport and AbstractTransport define the message pipeline, callbacks, and error handling. WebSocketMcpTransport adds a shared WebSocket implementation for both client and server sides, and ReadBuffer handles streaming JSON-RPC framing.
  • Protocol engine: The Protocol base class manages request/response correlation, notifications, progress tokens, and capability assertions. Higher-level modules extend it to become Client and Server.
  • Errors and safety: Common exception types (McpException, parsing errors) plus capability enforcement hooks ensure callers cannot use endpoints the peer does not advertise.

Typical usage

  • Import MCP types to define capabilities and message payloads for your own transports or custom integrations.
  • Extend Protocol if you need a bespoke peer role while reusing correlation logic and JSON-RPC helpers.
  • Use the DSL builders to construct well-typed requests (tools, prompts, resources, logging, completion) instead of crafting raw JSON.

Example: building a tool call request

val request = CallToolRequest {
    name = "summarize"
    arguments = mapOf("text" to "Hello MCP")
}

Example: parsing a JSON-RPC message

val message: JSONRPCMessage = McpJson.decodeFromString(jsonString)

Use this module when you need the raw building blocks of MCP—types, JSON config, and transport base classes—whether to embed in another runtime, author new transports, or contribute higher-level features in the client/server modules. The APIs are explicit to keep the shared surface stable for downstream users.