Kotlin MCP Expert

Your specialized agent for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library, covering server design, tool implementation, resource management, and deployment.

When to Use This Agent

Choose Kotlin MCP Expert when:

• Building MCP servers in Kotlin using the official SDK
• Implementing MCP tools, resources, and prompts in Kotlin
• Configuring MCP transport layers (stdio, SSE)
• Integrating Kotlin MCP servers with Claude Code or other MCP clients
• Testing and deploying MCP servers as standalone applications

Consider alternatives when:

• You need MCP servers in TypeScript — use the TypeScript MCP tools
• You need MCP servers in PHP — use the PHP MCP Expert agent
• You need general Kotlin development — use a Kotlin developer agent

Quick Start

Copy
# .claude/agents/kotlin-mcp.yml
name: Kotlin MCP Expert
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Kotlin MCP server specialist using the official kotlin-sdk for building tools, resources, and prompts

Example invocation:

claude "Create a Kotlin MCP server that provides database query tools — it should support listing tables, describing schemas, and executing read-only SQL queries with parameterized inputs"

Core Concepts

Kotlin MCP Server Structure

Copy
// build.gradle.kts
dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:0.4.0")
    implementation("io.ktor:ktor-server-netty:2.3.7")
}

// Main.kt
fun main() {
    val server = McpServer(
        name = "my-kotlin-mcp-server",
        version = "1.0.0",
        transport = StdioTransport()
    )

    // Register tools
    server.addTool(
        name = "query_database",
        description = "Execute a read-only SQL query",
        inputSchema = JsonObject(mapOf(
            "type" to JsonPrimitive("object"),
            "properties" to JsonObject(mapOf(
                "query" to JsonObject(mapOf(
                    "type" to JsonPrimitive("string"),
                    "description" to JsonPrimitive("SQL query to execute")
                ))
            )),
            "required" to JsonArray(listOf(JsonPrimitive("query")))
        ))
    ) { arguments ->
        val query = arguments["query"]?.jsonPrimitive?.content
        // Execute query and return results
        ToolResult(content = listOf(TextContent(queryResult)))
    }

    server.start()
}

MCP Components

Component	Purpose	Kotlin Implementation
Tools	Actions the client can invoke	server.addTool(name, schema) { handler }
Resources	Data the client can read	server.addResource(uri, name) { handler }
Prompts	Template prompts for the client	server.addPrompt(name, args) { handler }
Transport	Communication channel	StdioTransport() or SseTransport()

Configuration

Parameter	Description	Default
sdk_version	Kotlin MCP SDK version	0.4.0
transport	Transport type (stdio, sse)	stdio
kotlin_version	Kotlin language version	2.0
build_tool	Build system (gradle-kotlin, gradle-groovy)	gradle-kotlin
serialization	JSON library (kotlinx-serialization, gson)	kotlinx-serialization

Best Practices

1. Use kotlinx.serialization for type-safe JSON handling. Define data classes with @Serializable for tool inputs and outputs. This catches schema mismatches at compile time rather than runtime, and provides automatic JSON parsing and generation.

2. Validate tool inputs before processing. Don't trust that the client sends valid parameters. Check for required fields, validate types, and return clear error messages for invalid inputs. The MCP protocol supports error responses — use them.

3. Keep tools focused and composable. One tool that does one thing well is better than one tool that handles multiple operations. Clients can chain multiple tool calls, so design for composition rather than monolithic tools.

4. Use coroutines for async tool handlers. Kotlin's coroutine support integrates naturally with MCP's async nature. Use suspend functions in tool handlers for I/O operations (database queries, HTTP calls) to avoid blocking the server.

5. Package as a standalone JAR for easy distribution. Use the Gradle application plugin or Shadow plugin to create a fat JAR. This simplifies installation — users just need Java installed, and they can run the server with java -jar server.jar.

Common Issues

MCP client doesn't discover the server's tools. The server must respond to the tools/list request correctly. Verify that all tools are registered before server.start() is called, and that the tool schemas match the MCP specification format.

stdio transport conflicts with application logging. When using stdio transport, all communication happens over stdin/stdout. Any println() or logging to stdout corrupts the MCP protocol. Configure logging to stderr or a file instead.

Kotlin serialization fails on complex nested types. Deeply nested JSON structures with polymorphic types require explicit serializer registration. Use @Contextual annotations or register custom serializers in the SerializersModule for non-standard types.