kotlin-sdk — Claude MCP 必备工具中文教程

Overview

The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This Kotlin SDK implements the MCP specification, making it easy to:

• Build MCP clients that can connect to any MCP server
• Create MCP servers that expose resources, prompts, and tools
• Target JVM, Native, JS, and Wasm from a single codebase
• Use standard transports like stdio, SSE, Streamable HTTP, and WebSocket
• Handle MCP protocol messages and lifecycle events with coroutine-friendly APIs

Capabilities

Capabilities define what features a server or client supports. They are declared during initialization and determine what operations are available.

Server Capabilities

Servers declare their capabilities to inform clients what features they provide:

Client Capabilities

Clients declare their capabilities to inform servers what features they support:

Server Features

The Server API lets you wire prompts, resources, and tools with only a few lines of Kotlin. Each feature is registered up front and then resolved lazily when a client asks for it, so your handlers stay small and suspendable.

Prompts

Prompts are user-controlled templates that clients discover via prompts/list and fetch with prompts/get when a user chooses one (think slash commands or saved flows). They’re best for repeatable, structured starters rather than ad-hoc model calls.

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            prompts = ServerCapabilities.Prompts(listChanged = true),
        ),
    )
)

server.addPrompt(
    name = "code-review",
    description = "Ask the model to review a diff",
    arguments = listOf(
        PromptArgument(name = "diff", description = "Unified diff", required = true),
    ),
) { request ->
    GetPromptResult(
        description = "Quick code review helper",
        messages = listOf(
            PromptMessage(
                role = Role.User,
                content = TextContent(text = "Review this change:\n${request.arguments?.get("diff")}"),
            ),
        ),
    )
}

Use prompts for anything that deserves a template: bug triage questions, onboarding checklists, or saved searches. Set listChanged = true only if your prompt catalog can change at runtime and your server will emit notifications/prompts/list_changed when it does.

Resources

Resources are application-driven context that clients discover via resources/list or resources/templates/list, then fetch with resources/read. Register each one with a stable URI and return a ReadResourceResult when asked—contents can be text or binary blobs.

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            resources = ServerCapabilities.Resources(subscribe = true, listChanged = true),
        ),
    )
)

server.addResource(
    uri = "note://release/latest",
    name = "Release notes",
    description = "Last deployment summary",
    mimeType = "text/markdown",
) { request ->
    ReadResourceResult(
        contents = listOf(
            TextResourceContents(
                text = "Ship 42 reached production successfully.",
                uri = request.uri,
                mimeType = "text/markdown",
            ),
        ),
    )
}

Resources can be static text, generated JSON, or blobs—anything the client can surface to the user or inject into the model context. Set subscribe = true if you emit notifications/resources/updated for changes to specific URIs, and listChanged = true if you’ll send notifications/resources/list_changed when the catalog itself changes.

Tools

Tools are model-controlled capabilities the client exposes to the model. Clients discover them via tools/list, invoke them with tools/call, and your handlers receive JSON arguments, can emit streaming logs or progress, and return a CallToolResult. Keep a human in the loop for sensitive operations.

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            tools = ServerCapabilities.Tools(listChanged = true),
        ),
    )
)

server.addTool(
    name = "echo",
    description = "Return whatever the user sent back to them",
) { request ->
    val text = request.arguments?.get("text")?.jsonPrimitive?.content ?: "(empty)"
    CallToolResult(content = listOf(TextContent(text = "Echo: $text")))
}

Register as many tools as you need—long-running jobs can report progress via the request context, and tools can also trigger sampling (see below) when they need the client’s LLM. Set listChanged = true only if your tool catalog can change at runtime and your server will emit notifications/tools/list_changed when it does.

Completion

Completion provides argument suggestions for prompts or resource templates. Declare the completions capability and handle completion/complete requests to return up to 100 ranked values (include total/hasMore if you paginate).

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            completions = ServerCapabilities.Completions,
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

session.setRequestHandler<CompleteRequest>(Method.Defined.CompletionComplete) { request, _ ->
    val options = listOf("kotlin", "compose", "coroutine")
    val matches = options.filter { it.startsWith(request.argument.value.lowercase()) }

    CompleteResult(
        completion = CompleteResult.Completion(
            values = matches.take(3),
            total = matches.size,
            hasMore = matches.size > 3,
        ),
    )
}

Use context.arguments to refine suggestions for dependent fields (e.g., framework list filtered by chosen language).

Logging

Logging lets the server stream structured log notifications to the client using RFC 5424 levels (debug → emergency). Declare the logging capability; clients can raise the minimum level with logging/setLevel, and the server emits notifications/message with severity, optional logger name, and JSON data.

val server = Server(
    serverInfo = Implementation("example-server", "1.0.0"),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            logging = ServerCapabilities.Logging,
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

session.sendLoggingMessage(
    LoggingMessageNotification(
        LoggingMessageNotificationParams(
            level = LoggingLevel.Info,
            logger = "startup",
            data = buildJsonObject { put("message", "Server started") },
        ),
    ),
)

Keep logs free of sensitive data, and expect clients to surface them in their own UI.

Pagination

List operations return paginated results with an opaque nextCursor, clients echo that cursor to fetch the next page. Supported list calls: resources/list, resources/templates/list, prompts/list, and tools/list. Treat cursors as opaque—don’t parse or persist them across sessions.

val server = Server(
    serverInfo = Implementation("example-server", "1.0.0"),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            resources = ServerCapabilities.Resources(),
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

val resources = listOf(
    Resource(uri = "note://1", name = "Note 1", description = "First"),
    Resource(uri = "note://2", name = "Note 2", description = "Second"),
    Resource(uri = "note://3", name = "Note 3", description = "Third"),
)
val pageSize = 2

session.setRequestHandler<ListResourcesRequest>(Method.Defined.ResourcesList) { request, _ ->
    val start = request.params?.cursor?.toIntOrNull() ?: 0
    val page = resources.drop(start).take(pageSize)
    val next = if (start + page.size < resources.size) (start + page.size).toString() else null

    ListResourcesResult(
        resources = page,
        nextCursor = next,
    )
}

Include nextCursor only when more items remain an absent cursor ends pagination.

Client Features

Clients advertise their capabilities (roots, sampling, elicitation, etc.) during initialization. After that they can serve requests from the server while still initiating calls such as listTools or callTool.

Roots

Roots let the client declare where the server is allowed to operate. Declare the roots capability, respond to roots/list, and emit notifications/roots/list_changed if you set listChanged = true. URIs must be file:// paths.

val client = Client(
    clientInfo = Implementation("demo-client", "1.0.0"),
    options = ClientOptions(
        capabilities = ClientCapabilities(roots = ClientCapabilities.Roots(listChanged = true)),
    ),
)

client.addRoot(
    uri = "file:///Users/demo/projects",
    name = "Projects",
)
client.sendRootsListChanged()

Call addRoot/removeRoot whenever your file system view changes, and use sendRootsListChanged() to notify the server. Keep root lists user-controlled and revoke entries that are no longer authorized.

Sampling

Sampling lets the server ask the client to call its preferred LLM. Declare the sampling capability (and sampling.tools if you allow tool-enabled sampling), and handle sampling/createMessage. Keep a human in the loop for approvals.

val client = Client(
    clientInfo = Implementation("demo-client", "1.0.0"),
    options = ClientOptions(
        capabilities = ClientCapabilities(
            sampling = buildJsonObject { putJsonObject("tools") { } }, // drop tools if you don't support tool use
        ),
    ),
)

client.setRequestHandler<CreateMessageRequest>(Method.Defined.SamplingCreateMessage) { request, _ ->
    val content = request.messages.lastOrNull()?.content
    val prompt = if (content is TextContent) content.text else "your topic"
    CreateMessageResult(
        model = "gpt-4o-mini",
        role = Role.Assistant,
        content = TextContent(text = "Here is a short note about $prompt"),
    )
}

Inside the handler you can pick any model/provider, require approvals, or reject the request. If you don’t support tool use, omit sampling.tools from capabilities.

[//]: # (TODO: add elicitation section)

[//]: # (#### Elicitation)