Compiler-driven framework builds clients and servers using the Model Context Protocol, implementing JSON-RPC handlers, schema metadata, and lifecycle management. Features resource exposure, parameterized prompts, and transport logging.
mcp4k is a compiler-driven framework for building both clients and servers using the Model Context Protocol (MCP) in Kotlin. It implements the vast majority of the MCP specification, including resources, prompts, tools, sampling, and more.
mcp4k automatically generates JSON-RPC handlers, schema metadata, and manages the complete lifecycle for you.
stdio, with HTTP-Streaming and other transports on the roadmap.mcp4k also enforces correct parameter typing at compile time. If you describe a tool parameter incorrectly, you get a compile-time error instead of a runtime mismatch.
Add mcp4k to your build:
plugins {
kotlin("multiplatform") version "2.4.0" // or kotlin("jvm")
kotlin("plugin.serialization") version "2.4.0"
id("sh.ondr.mcp4k") version "0.4.11" // <-- Add this
}
mcp4k includes a compiler plugin that requires exact Kotlin version matching. Each mcp4k version is hard-linked to a specific Kotlin version:
/**
* Reverses an input string
*
* @param input The string to be reversed
*/
@McpTool
fun reverseString(input: String): ToolContent {
return "Reversed: ${input.reversed()}".toTextContent()
}
= runBlocking {
server = Server.Builder()
.withTool(::reverseString)
.withTransport(StdioTransport())
.build()
server.start()
() {
delay()
}
}
In this example, your new @McpTool is exposed via JSON-RPC as reverseString.
Clients can call it by sending tools/call messages.
fun main() = runBlocking {
val client = Client.Builder()
.withClientInfo("MyClient", "1.0.0")
.withTransport(StdioTransport())
.build()
client.start()
client.initialize()
}
All boilerplate (capability negotiation, JSON-RPC ID handling, etc.) is handled by mcp4k.
Once connected, the client can discover prompts/tools/resources and make calls according to the MCP spec:
val allTools = client.getAllTools()
println("Server tools = $allTools")
val response = client.callTool(
name = "reverseString",
arguments = buildMap {
put("input", JsonPrimitive("Some string we want reversed"))
},
)
val result = response.result?.deserializeResult<CallToolResult>()
println(result) // --> "desrever tnaw ew gnirts emoS"
If you want to get notified when the server changes its tools, you can provide a callback:
val client = Client.Builder()
// ...
.withOnToolsChanged { updatedTools: List<Tool> ->
println("Updated tools: $updatedTools")
}
.build()
You can observe raw incoming/outgoing messages by providing withTransportLogger lambdas:
val server = Server.Builder()
.withTransport(StdioTransport())
.withTransportLogger(
logIncoming = { msg -> println("SERVER INCOMING: $msg") },
logOutgoing = { msg -> println("SERVER OUTGOING: $msg") },
)
.build()
Both Server and Client accept this configuration. Super useful for debugging and tests.
Let's look at a more advanced tool example:
When clients call tools/list, they see a JSON schema describing the tool's input:
KDoc parameter descriptions are type-safe and will throw a compile-time error if you specify a non-existing property. Tool call invocation and type-safe deserialization will be handled by mcp4k.
Server can also add or remove tools at runtime:
server.addTool(::sendEmail)
// ...
server.removeTool(::sendEmail)
Both calls will automatically send ToolListChanged notifications to the client.
Tools can also be added or removed from inside tool functions if they are implemented as Server extension functions:
@McpTool
fun Server.toolThatAddsSecondTool(): ToolContent {
addTool(::secondTool)
return "Second tool added!".toTextContent()
}
Annotate functions with @McpPrompt to define parameterized conversation templates:
@McpPrompt
fun codeReviewPrompt(code: String) = buildPrompt {
user("Please review the following code:")
user("'''\n$code\n'''")
}
Clients can call prompts/get to retrieve the underlying messages.
In some cases, you want multiple tools or prompts to share state. mcp4k allows you to attach a custom context object that tools and prompts can reference.
ServerContext object.withContext(...)getContextAs()For example:
But looking at the above code, it doesn't make sense that the greetUser function is callable before setUserName has been called.
Thus, we can improve the code by doing:
fun main() {
val server = Server.Builder()
// ...
.withTool(Server::setUserName) // only add this
// ...
}
@McpTool
fun Server.setUserName(name: String): ToolContent {
getContextAs<MyServerContext>().userName = name
addTool(Server::greetUser) // Now, add greetUser
.toTextContent()
}
Resources in MCP allow servers to expose data that clients can read. The ResourceProvider interface is the core abstraction for implementing resource support:
You can implement this interface to expose any type of data as resources - databases, APIs, files, or any other data source.
For common file-based use cases, mcp4k provides ready-to-use implementations in the optional mcp4k-file-provider module. See the file provider documentation for details on:
DiscreteFileProvider - Expose specific files with discrete URIsTemplateFileProvider - Expose entire directories with URI templatesHere's a simple example of a custom resource provider:
Then add it to your server:
val server = Server.Builder()
.withResourceProvider(DatabaseResourceProvider())
.withTransport(StdioTransport())
.build()
Clients can fulfill server-initiated LLM requests by providing a SamplingProvider.
In a real application, you would call your favorite LLM API (e.g., OpenAI, Anthropic) inside the provider. Here’s a simplified example that always returns a dummy completion:
// 1) Define a sampling provider
val samplingProvider = SamplingProvider { params: CreateMessageParams ->
CreateMessageResult(
model = "dummy-model",
role = Role.ASSISTANT,
content = TextContent("Dummy completion result"),
stopReason = "endTurn",
)
}
// 2) Build the client with sampling support
val client = Client.Builder()
.withTransport(StdioTransport())
.withPermissionCallback { userApprovable ->
// Prompt the user for confirmation here
true
}
.withSamplingProvider(samplingProvider)
.build()
runBlocking {
client.start()
client.initialize()
}
mcp4k uses Kotlin coroutines for cooperative cancellation. For example, a long-running server tool:
@McpTool
suspend fun slowToolOperation(iterations: Int = 10): ToolContent {
for (i in 1..iterations) {
delay(1000)
}
return "Operation completed after $iterations".toTextContent()
}
The client can cancel mid-operation:
val requestJob = launch {
client.sendRequest { id ->
CallToolRequest(
id = id,
params = CallToolRequest.CallToolParams(
name = "slowToolOperation",
arguments = mapOf("iterations" to 20),
),
)
}
}
delay(600)
requestJob.cancel("User doesn't want to wait anymore")
Under the hood, mcp4k sends a notification to the server:
{
"method": "notifications/cancelled",
"jsonrpc": "2.0",
"params": {
"requestId": "2"
and the server will abort the suspended tool operation.
✅ Add resource capability
✅ @McpTool and @McpPrompt functions
✅ Request cancellations
✅ Pagination
✅ Sampling (client-side)
✅ Roots
✅ Transport logging
✅ onToolsChanged callback in Client
⬜ Support other Kotlin versions
⬜ Completions
⬜ Support logging levels
⬜ Proper version negotiation
⬜ Emit progress notifications from @McpTool functions
⬜ Proper MIME detection
⬜ Add FileWatcher automate resourcesupdated notifications
⬜ HTTPStreaming transport
⬜ , property descriptions validation keywords the JSON schemas
@McpTool and @McpPrompt functions are processed at compile time.Issues and pull requests are welcome! Feel free to open a discussion or contribute improvements.
License: mcp4k is available under the Apache License 2.0.
| mcp4k Version | Required Kotlin Version |
|---|
| 0.4.11 | 2.4.0 |
| 0.4.10 | 2.3.21 |
| 0.4.9 | 2.3.20 |
| 0.4.8 | 2.3.10 |
| 0.4.7 | 2.3.0 |
| 0.4.6 | 2.2.21 |
| 0.4.5 | 2.2.20 |
| 0.4.4 | 2.2.10 |
| 0.4.2 - 0.4.3 | 2.2.0 |
enum class Priority {
LOW, NORMAL, HIGH
}
/**
* @property title The email's title
* @property body The email's body
* @property priority The email's priority
*/
data class Email(
val title: String,
val body: String?,
val priority: Priority = Priority.NORMAL,
)
/**
* Sends an email
* @param recipients The email addresses of the recipients
* @param email The email to send
*/
fun sendEmail(
recipients: List<String>,
email: Email,
) = buildString {
append("Email sent to ${recipients.joinToString()} with ")
append("title '${email.title}' and ")
append("body '${email.body}' and ")
append("priority ${email.priority}")
}.toTextContent()
{
"type": "object",
"description": "Sends an email",
"properties": {
"recipients": {
"type": "array",
"description": "The email addresses of the recipients",
"items": {
"type": "string"
}
},
"email": {
"type": "object",
"description": "The email to send",
"properties": {
"title": {
"type": "string",
"description": "The email's title"
},
"body": {
"type": "string",
"description": "The email's body"
},
"priority": {
"type": "string",
"description": "The email's priority",
"enum": [
"LOW",
"NORMAL",
"HIGH"
]
}
},
"required": [
"title"
]
}
},
"required": [
"recipients",
"email"
]
}
// 1) Create your context
class MyServerContext : ServerContext {
var userName: String = ""
}
// 2) A tool function that writes into the context
fun Server.setUserName(name: String): ToolContent {
getContextAs<MyServerContext>().userName = name
return "Username set to: $name".toTextContent()
}
// 3) Another tool that reads from the context
fun Server.greetUser(): ToolContent {
val name = getContextAs<MyServerContext>().userName
if (name.isEmpty()) return "No user set yet!".toTextContent()
return "Hello, $name!".toTextContent()
}
fun main() = runBlocking {
val context = MyServerContext()
val server = Server.Builder()
.withContext(context) // <-- Provide the context
.withTool(Server::setUserName)
.withTool(Server::greetUser)
.withTransport(StdioTransport())
.build()
server.start()
while(true) {
delay(1000)
}
}
interface ResourceProvider {
suspend fun listResources(): List<Resource>
suspend fun readResource(uri: String): ResourceContents
suspend fun listResourceTemplates(): List<ResourceTemplate>
suspend fun subscribe(uri: String)
suspend fun unsubscribe(uri: String)
fun onResourceListChanged(callback: () -> Unit)
fun onResourceUpdated(callback: (uri: String) -> Unit)
}
class DatabaseResourceProvider : ResourceProvider {
override suspend fun listResources(): List<Resource> {
return listOf(
Resource(
uri = "db://users",
name = "Users Table",
description = "Access to user data",
mimeType = "application/json"
)
)
}
override suspend fun readResource(uri: String): ResourceContents {
return when (uri) {
"db://users" -> ResourceContents(
uri = uri,
mimeType = "application/json",
text = fetchUsersAsJson()
)
else -> throw ResourceNotFoundException(uri)
}
}
// Implement other methods as needed...
}
Surfaced from shared tags and platforms — no rankings paid for.