kotlin-sdk-core/io.modelcontextprotocol.kotlin.sdk

Package-level declarations

Types

data class Annotations(val audience: List<Role>?, val lastModified: Instant?, val priority: Double?)

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed.

data class AudioContent(val data: String, val mimeType: String, val annotations: Annotations? = null) : PromptMessageContentMultimodal

Audio provided to or from an LLM.

BlobResourceContents

@Serializable

data class BlobResourceContents(val blob: String, val uri: String, val mimeType: String?) : ResourceContents

Represents the binary contents of a resource encoded as a base64 string.

CallToolRequest

@Serializable

data class CallToolRequest(val name: String, val arguments: JsonObject = EmptyJsonObject, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

Used by the client to invoke a tool provided by the server.

CallToolResult

@Serializable

class CallToolResult(val content: List<PromptMessageContent>, val structuredContent: JsonObject? = null, val isError: Boolean? = false, val _meta: JsonObject = EmptyJsonObject) : CallToolResultBase

The server's response to a tool call.

CallToolResultBase

@Serializable

sealed interface CallToolResultBase : ServerResult

The server's response to a tool call.

CancelledNotification

@Serializable

data class CancelledNotification(val params: CancelledNotification.Params) : ClientNotification, ServerNotification

This notification can be sent by either side to indicate that it is cancelling a previously issued request.

ClientCapabilities

@Serializable

data class ClientCapabilities(val experimental: JsonObject? = EmptyJsonObject, val sampling: JsonObject? = EmptyJsonObject, val roots: ClientCapabilities.Roots? = null, val elicitation: JsonObject? = null)

Capabilities a client may support. Known capabilities are defined here, in this, but this is not a closed set: any client can define its own, additional capabilities.

ClientNotification

@Serializable(with = ClientNotificationPolymorphicSerializer::class)

sealed interface ClientNotification : Notification

Represents a notification sent by the client.

ClientRequest

interface ClientRequest : Request

Represents a request sent by the client.

ClientResult

@Serializable(with = ClientResultPolymorphicSerializer::class)

sealed interface ClientResult : RequestResult

Represents a result returned to the client.

CompatibilityCallToolResult

@Serializable

class CompatibilityCallToolResult(val content: List<PromptMessageContent>, val structuredContent: JsonObject? = null, val isError: Boolean? = false, val _meta: JsonObject = EmptyJsonObject, val toolResult: JsonObject = EmptyJsonObject) : CallToolResultBase

CallToolResult extended with backwards compatibility to protocol version 2024-11-05.

CompleteRequest

@Serializable

data class CompleteRequest(val ref: Reference, val argument: CompleteRequest.Argument, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

A request from the client to the server to ask for completion options.

CompleteResult

@Serializable

data class CompleteResult(val completion: CompleteResult.Completion, val _meta: JsonObject = EmptyJsonObject) : ServerResult

The server's response to a completion/complete request

CreateElicitationRequest

@Serializable

data class CreateElicitationRequest(val message: String, val requestedSchema: CreateElicitationRequest.RequestedSchema, val _meta: JsonObject = EmptyJsonObject) : ServerRequest, WithMeta

Sent from the server to create an elicitation from the client.

CreateElicitationResult

@Serializable

data class CreateElicitationResult(val action: CreateElicitationResult.Action, val content: JsonObject? = null, val _meta: JsonObject = EmptyJsonObject) : ClientResult

The client's response to an elicitation/create request from the server.

CreateMessageRequest

@Serializable

data class CreateMessageRequest(val messages: List<SamplingMessage>, val systemPrompt: String?, val includeContext: CreateMessageRequest.IncludeContext?, val temperature: Double?, val maxTokens: Int, val stopSequences: List<String>?, val metadata: JsonObject = EmptyJsonObject, val modelPreferences: ModelPreferences?, val _meta: JsonObject = EmptyJsonObject) : ServerRequest, WithMeta

A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling to allow them to inspect the request (human in the loop) and decide whether to approve it.

CreateMessageResult

@Serializable

data class CreateMessageResult(val model: String, val stopReason: StopReason? = null, val role: Role, val content: PromptMessageContentMultimodal, val _meta: JsonObject = EmptyJsonObject) : ClientResult

The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.

Cursor

typealias Cursor = String

An opaque token used to represent a cursor for pagination.

CustomMeta

@Serializable

class CustomMeta(val _meta: JsonObject = EmptyJsonObject) : WithMeta

An implementation of WithMeta containing custom metadata.

CustomRequest

@Serializable

open class CustomRequest(val method: Method) : Request

A custom request with a specified method.

EmbeddedResource

@Serializable

data class EmbeddedResource(val resource: ResourceContents, val annotations: Annotations? = null) : PromptMessageContent

The contents of a resource, embedded into a prompt or tool call result.

EmptyRequestResult

@Serializable

data class EmptyRequestResult(val _meta: JsonObject = EmptyJsonObject) : ServerResult, ClientResult

An empty result for a request containing optional metadata.

ErrorCode

@Serializable(with = ErrorCodeSerializer::class)

sealed interface ErrorCode

An incomplete set of error codes that may appear in JSON-RPC responses.

GetPromptRequest

@Serializable

data class GetPromptRequest(val name: String, val arguments: Map<String, String>?, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

Used by the client to get a prompt provided by the server.

GetPromptResult

@Serializable

class GetPromptResult(val description: String?, val messages: List<PromptMessage>, val _meta: JsonObject = EmptyJsonObject) : ServerResult

The server's response to a prompts/get request from the client.

ImageContent

@Serializable

data class ImageContent(val data: String, val mimeType: String, val annotations: Annotations? = null) : PromptMessageContentMultimodal

An image provided to or from an LLM.

Implementation

@Serializable

data class Implementation(val name: String, val version: String)

Describes the name and version of an MCP implementation.

InitializedNotification

@Serializable

data class InitializedNotification(val params: InitializedNotification.Params = Params()) : ClientNotification

This notification is sent from the client to the server after initialization has finished.

InitializeRequest

@Serializable

data class InitializeRequest(val protocolVersion: String, val capabilities: ClientCapabilities, val clientInfo: Implementation, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

This request is sent from the client to the server when it first connects, asking it to begin initialization.

InitializeResult

@Serializable

data class InitializeResult(val protocolVersion: String = LATEST_PROTOCOL_VERSION, val capabilities: ServerCapabilities = ServerCapabilities(), val serverInfo: Implementation, val instructions: String? = null, val _meta: JsonObject = EmptyJsonObject) : ServerResult

After receiving an initialized request from the client, the server sends this response.

JSONRPCError

@Serializable

data class JSONRPCError(val code: ErrorCode, val message: String, val data: JsonObject = EmptyJsonObject) : JSONRPCMessage

A response to a request that indicates an error occurred.

JSONRPCMessage

@Serializable(with = JSONRPCMessagePolymorphicSerializer::class)

sealed interface JSONRPCMessage

Represents a JSON-RPC message in the protocol.

JSONRPCNotification

@Serializable

data class JSONRPCNotification(val method: String, val params: JsonElement = EmptyJsonObject, val jsonrpc: String = JSONRPC_VERSION) : JSONRPCMessage

A notification which does not expect a response.

JSONRPCRequest

@Serializable

data class JSONRPCRequest(val id: RequestId = RequestId.NumberId(REQUEST_MESSAGE_ID.incrementAndFetch()), val method: String, val params: JsonElement = EmptyJsonObject, val jsonrpc: String = JSONRPC_VERSION) : JSONRPCMessage

A request that expects a response.

JSONRPCResponse

@Serializable

class JSONRPCResponse(val id: RequestId, val jsonrpc: String = JSONRPC_VERSION, val result: RequestResult? = null, val error: JSONRPCError? = null) : JSONRPCMessage

A successful (non-error) response to a request.

ListPromptsRequest

@Serializable

data class ListPromptsRequest(val cursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, PaginatedRequest

Sent from the client to request a list of prompts and prompt templates the server has.

ListPromptsResult

@Serializable

class ListPromptsResult(val prompts: List<Prompt>, val nextCursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ServerResult, PaginatedResult

The server's response to a prompts/list request from the client.

ListResourcesRequest

@Serializable

data class ListResourcesRequest(val cursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, PaginatedRequest

Sent from the client to request a list of resources the server has.

ListResourcesResult

@Serializable

class ListResourcesResult(val resources: List<Resource>, val nextCursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ServerResult, PaginatedResult

The server's response to a resources/list request from the client.

ListResourceTemplatesRequest

@Serializable

data class ListResourceTemplatesRequest(val cursor: Cursor?, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, PaginatedRequest

Sent from the client to request a list of resource templates the server has.

ListResourceTemplatesResult

@Serializable

class ListResourceTemplatesResult(val resourceTemplates: List<ResourceTemplate>, val nextCursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ServerResult, PaginatedResult

The server's response to a resources/templates/list request from the client.

ListRootsRequest

@Serializable

class ListRootsRequest(val _meta: JsonObject = EmptyJsonObject) : ServerRequest, WithMeta

Sent from the server to request a list of root URIs from the client.

ListRootsResult

@Serializable

class ListRootsResult(val roots: List<Root>, val _meta: JsonObject = EmptyJsonObject) : ClientResult

The client's response to a roots/list request from the server.

ListToolsRequest

@Serializable

data class ListToolsRequest(val cursor: Cursor? = null, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, PaginatedRequest

Sent from the client to request a list of tools the server has.

ListToolsResult

@Serializable

class ListToolsResult(val tools: List<Tool>, val nextCursor: Cursor?, val _meta: JsonObject = EmptyJsonObject) : ServerResult, PaginatedResult

The server's response to a tools/list request from the client.

LoggingLevel

@Serializable

enum LoggingLevel : Enum<LoggingLevel>

The severity of a log message.

LoggingMessageNotification

@Serializable

data class LoggingMessageNotification(val params: LoggingMessageNotification.Params) : ServerNotification

Notification of a log message passed from server to client. If no logging level request has been sent from the client, the server MAY decide which messages to send automatically.

McpError

class McpError(val code: Int, message: String, val data: JsonObject = EmptyJsonObject) : Exception

Represents an error specific to the MCP protocol.

Method

@Serializable(with = RequestMethodSerializer::class)

sealed interface Method

Represents a method in the protocol, which can be predefined or custom.

ModelHint

@Serializable

data class ModelHint(val name: String?)

Hints to use for model selection.

ModelPreferences

@Serializable

class ModelPreferences(val hints: List<ModelHint>?, val costPriority: Double?, val speedPriority: Double?, val intelligencePriority: Double?)

The server's preferences for model selection, requested by the client during sampling.

Notification

@Serializable(with = NotificationPolymorphicSerializer::class)

sealed interface Notification

Represents a notification in the protocol.

NotificationParams

@Serializable

sealed interface NotificationParams : WithMeta

Base interface for notification parameters with optional metadata.

PaginatedRequest

@Serializable

sealed interface PaginatedRequest : Request, WithMeta

Represents a request supporting pagination.

PaginatedResult

@Serializable

sealed interface PaginatedResult : RequestResult

Represents a paginated result of a request.

PingRequest

@Serializable

class PingRequest : ServerRequest, ClientRequest

A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else it may be disconnected.

Progress

@Serializable

open class Progress(val progress: Double, val total: Double?, val message: String?) : ProgressBase

Represents a progress notification.

ProgressBase

@Serializable

sealed interface ProgressBase

Represents the base interface for progress tracking.

ProgressNotification

@Serializable

data class ProgressNotification(val params: ProgressNotification.Params) : ClientNotification, ServerNotification

An out-of-band notification used to inform the receiver of a progress update for a long-running request.

ProgressToken

typealias ProgressToken = RequestId

A progress token, used to associate progress notifications with the original request. Stores message ID.

Prompt

@Serializable

class Prompt(val name: String, val description: String?, val arguments: List<PromptArgument>?)

A prompt or prompt template that the server offers.

PromptArgument

@Serializable

data class PromptArgument(val name: String, val description: String?, val required: Boolean?)

Describes an argument that a prompt can accept.

PromptListChangedNotification

@Serializable

data class PromptListChangedNotification(val params: PromptListChangedNotification.Params = Params()) : ServerNotification

An optional notification from the server to the client, informing it that the list of prompts it offers has changed. Servers may issue this without any previous subscription from the client.

PromptMessage

@Serializable

data class PromptMessage(val role: Role, val content: PromptMessageContent)

Describes a message returned as part of a prompt.

PromptMessageContent

@Serializable(with = PromptMessageContentPolymorphicSerializer::class)

sealed interface PromptMessageContent

Represents the content of a prompt message.

PromptMessageContentMultimodal

@Serializable(with = PromptMessageContentMultimodalPolymorphicSerializer::class)

sealed interface PromptMessageContentMultimodal : PromptMessageContent

Represents prompt message content that is either text, image or audio.

PromptReference

@Serializable

data class PromptReference(val name: String) : Reference

Identifies a prompt.

ReadResourceRequest

@Serializable

data class ReadResourceRequest(val uri: String, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

Sent from the client to the server to read a specific resource URI.

ReadResourceResult

@Serializable

class ReadResourceResult(val contents: List<ResourceContents>, val _meta: JsonObject = EmptyJsonObject) : ServerResult

The server's response to a resources/read request from the client.

Reference

@Serializable(with = ReferencePolymorphicSerializer::class)

sealed interface Reference

Request

@Serializable(with = RequestPolymorphicSerializer::class)

sealed interface Request

Represents a request in the protocol.

RequestId

@Serializable(with = RequestIdSerializer::class)

sealed interface RequestId

A uniquely identifying ID for a request in JSON-RPC.

RequestIdSerializer

class RequestIdSerializer : KSerializer<RequestId>

RequestResult

@Serializable(with = RequestResultPolymorphicSerializer::class)

sealed interface RequestResult : WithMeta

Represents the result of a request, including additional metadata.

Resource

@Serializable

data class Resource(val uri: String, val name: String, val description: String?, val mimeType: String?, val title: String? = null, val size: Long? = null, val annotations: Annotations? = null)

A known resource that the server is capable of reading.

ResourceContents

@Serializable(with = ResourceContentsPolymorphicSerializer::class)

sealed interface ResourceContents

The contents of a specific resource or sub-resource.

ResourceListChangedNotification

@Serializable

data class ResourceListChangedNotification(val params: ResourceListChangedNotification.Params = Params()) : ServerNotification

An optional notification from the server to the client, informing it that the list of resources it can read from has changed. Servers may issue this without any previous subscription from the client.

ResourceTemplate

@Serializable

data class ResourceTemplate(val uriTemplate: String, val name: String, val description: String?, val mimeType: String?, val title: String? = null, val annotations: Annotations? = null)

A template description for resources available on the server.

ResourceTemplateReference

@Serializable

data class ResourceTemplateReference(val uri: String) : Reference

A reference to a resource or resource template definition.

ResourceUpdatedNotification

@Serializable

data class ResourceUpdatedNotification(val params: ResourceUpdatedNotification.Params) : ServerNotification

A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request.

Role

@Serializable

enum Role : Enum<Role>

Enum representing the role of a participant.

Root

@Serializable

data class Root(val uri: String, val name: String?)

Represents a root directory or file that the server can operate on.

RootsListChangedNotification

@Serializable

data class RootsListChangedNotification(val params: RootsListChangedNotification.Params = Params()) : ClientNotification

A notification from the client to the server, informing it that the list of roots has changed.

SamplingMessage

@Serializable

data class SamplingMessage(val role: Role, val content: PromptMessageContentMultimodal)

Describes a message issued to or received from an LLM API.

ServerCapabilities

@Serializable

data class ServerCapabilities(val experimental: JsonObject? = EmptyJsonObject, val sampling: JsonObject? = EmptyJsonObject, val logging: JsonObject? = EmptyJsonObject, val prompts: ServerCapabilities.Prompts? = null, val resources: ServerCapabilities.Resources? = null, val tools: ServerCapabilities.Tools? = null)

Represents the capabilities that a server can support.

ServerNotification

@Serializable(with = ServerNotificationPolymorphicSerializer::class)

sealed interface ServerNotification : Notification

Represents a notification sent by the server.

ServerRequest

sealed interface ServerRequest : Request

Represents a request sent by the server.

ServerResult

@Serializable(with = ServerResultPolymorphicSerializer::class)

sealed interface ServerResult : RequestResult

Represents a result returned by the server.

StopReason

@Serializable(with = StopReasonSerializer::class)

sealed interface StopReason

SubscribeRequest

@Serializable

data class SubscribeRequest(val uri: String, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.

TextContent

@Serializable

data class TextContent(val text: String? = null, val annotations: Annotations? = null) : PromptMessageContentMultimodal

Text provided to or from an LLM.

TextResourceContents

@Serializable

data class TextResourceContents(val text: String, val uri: String, val mimeType: String?) : ResourceContents

Represents the text contents of a resource.

Tool

@Serializable

data class Tool(val name: String, val title: String?, val description: String?, val inputSchema: Tool.Input, val outputSchema: Tool.Output?, val annotations: ToolAnnotations?)

Definition for a tool the client can call.

ToolAnnotations

@Serializable

data class ToolAnnotations(val title: String?, val readOnlyHint: Boolean? = false, val destructiveHint: Boolean? = true, val idempotentHint: Boolean? = false, val openWorldHint: Boolean? = true)

Additional properties describing a Tool to clients.

ToolListChangedNotification

@Serializable

data class ToolListChangedNotification(val params: ToolListChangedNotification.Params = Params()) : ServerNotification

An optional notification from the server to the client, informing it that the list of tools it offers has changed. Servers may issue this without any previous subscription from the client.

UnknownContent

@Serializable

data class UnknownContent(val type: String) : PromptMessageContentMultimodal

Unknown content provided to or from an LLM.

UnknownMethodRequestOrNotification

@Serializable

data class UnknownMethodRequestOrNotification(val method: Method, val params: NotificationParams? = null) : ClientNotification, ClientRequest, ServerNotification, ServerRequest

Represents a request or notification for an unknown method.

UnknownReference

@Serializable

data class UnknownReference(val type: String) : Reference

Identifies a prompt.

UnknownResourceContents

@Serializable

data class UnknownResourceContents(val uri: String, val mimeType: String?) : ResourceContents

Represents resource contents with unknown or unspecified data.

UnsubscribeRequest

@Serializable

data class UnsubscribeRequest(val uri: String, val _meta: JsonObject = EmptyJsonObject) : ClientRequest, WithMeta

Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.

WithMeta

@Serializable

sealed interface WithMeta

Represents an entity that includes additional metadata in its responses.