Server Samples

Sample projects demonstrating ktmcp - a Kotlin library for building Model Context Protocol (MCP) servers.

Samples

stdio-basic

MCP server using stdio transport - communicates via stdin/stdout using JSON-RPC. Ideal for CLI tools and local integrations.

Features demonstrated:

• Tools with typed arguments and responses (@Serializable data classes)
• Tools with untyped arguments (dynamic arguments map)
• Dynamic tool/resource creation at runtime
• Prompts with arguments
• Resources with subscription support
• Resource templates with URI parameters
• Session lifecycle hooks

ktor-basic

MCP server using Ktor SSE transport - exposes MCP over HTTP using Server-Sent Events. Ideal for web services and remote integrations.

Features demonstrated:

• Ktor routing integration
• Tools with typed arguments and responses
• Prompts
• Resources with subscriptions
• Accessing Ktor's ApplicationCall and logger

Requirements

• JDK 21+
• Gradle 8.x

Building

# Build all samples
./gradlew build

# Build fat JAR for stdio-basic (includes all dependencies)
./gradlew :stdio-basic:shadowJar

Running

stdio-basic

# Run directly
./gradlew :stdio-basic:run

# Or run the fat JAR
java -jar stdio-basic/build/libs/stdio-basic.jar

ktor-basic

# Starts HTTP server on port 3001
./gradlew :ktor-basic:run

The MCP endpoint will be available at http://localhost:3001/mcp

Configuration

ktmcp Version

Set the ktmcp version in gradle.properties:

ktmcpVersion=0.7.0

Logging

Both samples use SLF4J SimpleLogger. Configure via src/main/resources/simplelogger.properties:

# Set log level for ktmcp
org.slf4j.simpleLogger.log.org.ktmcp.server=debug

For stdio-basic, logs go to stderr by default (stdout is reserved for JSON-RPC).

License

Apache 2.0