kotlin-sdk/docs/moduledoc.md

MCP Kotlin SDK

Kotlin Multiplatform implementation of the Model Context Protocol (MCP). The SDK focuses on clear, explicit APIs, small building blocks, and first-class coroutine support so clients and servers share the same well-typed messages and transports.

Use the umbrella kotlin-sdk artifact to bring in everything at once, or depend on the focused modules directly:

dependencies {
    // All-in-one bundle
    implementation("io.modelcontextprotocol:kotlin-sdk:<version>")

    // Or pick sides explicitly
    implementation("io.modelcontextprotocol:kotlin-sdk-client:<version>")
    implementation("io.modelcontextprotocol:kotlin-sdk-server:<version>")
}

---

Module kotlin-sdk-core

Foundation shared by both sides:

• Protocol data model for MCP requests, results, notifications, capabilities, and content types.
• McpJson (kotlinx.serialization) with MCP-friendly defaults plus helpers for converting native values to JSON.
• Transport abstractions (Transport, AbstractTransport, WebSocketMcpTransport) and streaming ReadBuffer.
• Protocol base class that handles JSON-RPC framing, correlation, progress tokens, and capability assertions.

Use core when you need the raw types or want to author a custom transport. Public APIs are explicit to keep the shared surface stable across platforms.

---

Module kotlin-sdk-client

High-level client for connecting to MCP servers and invoking their features:

• Client runtime (or mcpClient helper) performs the MCP handshake and exposes serverCapabilities, serverVersion, and serverInstructions.
• Typed operations for tools, prompts, resources, completion, logging, roots, sampling, and elicitation with capability enforcement.
• Transports: StdioClientTransport, SseClientTransport, WebSocketClientTransport, and StreamableHttpClientTransport, plus Ktor client extensions for quick wiring.

Minimal WebSocket client:

val client = mcpClient(
    clientInfo = Implementation("sample-client", "1.0.0"),
    clientOptions = ClientOptions(ClientCapabilities(tools = ClientCapabilities.Tools())),
    transport = WebSocketClientTransport("ws://localhost:8080/mcp")
)

val tools = client.listTools()
val result = client.callTool("echo", mapOf("text" to "Hello, MCP!"))
println(result.content)

---

Module kotlin-sdk-server

Server toolkit for exposing MCP tools, prompts, and resources:

• Server runtime coordinates sessions, initialization flow, and capability enforcement with registries for tools, prompts, resources, and templates.
• Transports: StdioServerTransport for CLI/editor bridges; Ktor extensions (mcp for SSE + POST back-channel and mcpWebSocket for WebSocket) for HTTP hosting.
• Built-in notifications for list changes and resource subscriptions when capabilities enable them.

Minimal Ktor SSE server:

fun Application.module() {
    mcp {
        Server(
            serverInfo = Implementation("sample-server", "1.0.0"),
            options = ServerOptions(ServerCapabilities(
                tools = ServerCapabilities.Tools(listChanged = true),
                resources = ServerCapabilities.Resources(listChanged = true, subscribe = true),
            )),
        ) {
            addTool(name = "echo", description = "Echo text back") { request ->
                val text = request.params.arguments?.get("text")?.jsonPrimitive?.content ?: ""
                CallToolResult(content = listOf(TextContent("You said: $text")))
            }
        }
    }
}

Pick the module that matches your role, or use the umbrella artifact to get both sides with the shared core.