Module mcp
ballerina/mcp Ballerina library
Overview
Clients
mcp: Client
Represents an MCP client built on top of the Streamable HTTP transport.
Constructor
Initializes a new MCP client with the provided server URL and client details.
init (string serverUrl, Implementation clientInfo, ClientConfiguration? config)- serverUrl string - MCP server URL.
- clientInfo Implementation - Client details, such as name and version.
- config ClientConfiguration? () - Optional configuration containing client capabilities.
initialize
function initialize() returns ClientError?Establishes a connection to the MCP server and performs protocol initialization.
Return Type
- ClientError? - A ClientError if initialization fails, or nil on success.
subscribeToServerMessages
function subscribeToServerMessages() returns stream<JsonRpcMessage, StreamError?>|ClientErrorOpens a server-sent events (SSE) stream for asynchronous server-to-client communication.
Return Type
- stream<JsonRpcMessage, StreamError?>|ClientError - Stream of JsonRpcMessages or a ClientError.
listTools
function listTools() returns ListToolsResult|ClientErrorRetrieves the list of available tools from the server.
Return Type
- ListToolsResult|ClientError - List of available tools or a ClientError.
callTool
function callTool(CallToolParams params) returns CallToolResult|ClientErrorExecutes a tool on the server with the given parameters.
Parameters
- params CallToolParams - Tool execution parameters, including name and arguments.
Return Type
- CallToolResult|ClientError - Result of the tool execution or a ClientError.
close
function close() returns ClientError?Closes the session and disconnects from the server.
Return Type
- ClientError? - A ClientError if closure fails, or nil on success.
Constants
Records
mcp: Annotations
Optional annotations for the client. The client can use annotations to inform how objects are used or displayed
Fields
- audience? Role[] - Describes who the intended customer of this object or data is.
This can include multiple entries to indicate content useful for multiple audiences (e.g.,
["user", "assistant"]).
- priority? decimal - Describes how important this data is for operating the server. A value of 1 means "most important," and indicates that the data is effectively required, while 0 means "least important," and indicates that the data is entirely optional.
mcp: AudioContent
Audio provided to or from an LLM.
Fields
- 'type "audio" - The type of content
- data string - The base64-encoded audio data
- mimeType string - The MIME type of the audio. Different providers may support different audio types.
- annotations? Annotations - Optional annotations for the client
mcp: BlobResourceContents
Binary resource contents
Fields
- Fields Included from *ResourceContents
- blob string - A base64-encoded string representing the binary data of the item.
mcp: CallToolParams
Parameters for the tools/call request
Fields
- name string - The name of the tool to invoke
- arguments? record {} - Optional arguments to pass to the tool
mcp: CallToolRequest
Used by the client to invoke a tool provided by the server.
Fields
- method "tools/call" - The JSON-RPC method name
- params CallToolParams - The parameters for the tool call
mcp: CallToolResult
The server's response to a tool call.
Fields
- content (TextContent|ImageContent|AudioContent|EmbeddedResource)[] - The content of the tool call result
- isError? boolean - Whether the tool call ended in an error. If not set, this is assumed to be false (the call was successful).
mcp: CancelledNotification
This notification can be sent by either side to indicate that it is cancelling a previously-issued request.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/cancelled" - The method name for this notification
mcp: ClientCapabilities
Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.
Fields
- experimental? record { record {}... } - Experimental, non-standard capabilities that the client supports.
- roots? record {| listChanged boolean |} - Present if the client supports listing roots.
- sampling? record {} - Present if the client supports sampling from an LLM.
mcp: ClientConfiguration
Configuration options for initializing an MCP client.
Fields
- Fields Included from *ProtocolOptions
- enforceStrictCapabilities boolean
- capabilities? ClientCapabilities - Capabilities to be advertised by this client.
mcp: EmbeddedResource
The contents of a resource, embedded into a prompt or tool call result.
Fields
- 'type "resource" - The type of content
- 'resource TextResourceContents|BlobResourceContents - The resource content
- annotations? Annotations - Optional annotations for the client
mcp: ImageContent
An image provided to or from an LLM.
Fields
- 'type "image" - The type of content
- data string - The base64-encoded image data
- mimeType string - The MIME type of the image. Different providers may support different image types.
- annotations? Annotations - Optional annotations for the client
mcp: Implementation
Describes the name and version of an MCP implementation.
Fields
- name string - The name of the implementation
- version string - The version of the implementation
mcp: InitializedNotification
This notification is sent from the client to the server after initialization has finished.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/initialized" - The method identifier for the notification, must be "notifications/initialized"
mcp: InitializeResult
After receiving an initialize request from the client, the server sends this response.
Fields
- Fields Included from *Result
- _meta record { anydata... }
- anydata...
- protocolVersion string - The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.
- capabilities ServerCapabilities - The capabilities of the server.
- serverInfo Implementation - Information about the server implementation
- instructions? string - Instructions describing how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
mcp: JsonRpcError
A response to a request that indicates an error occurred.
Fields
- jsonrpc JSONRPC_VERSION - The JSON-RPC protocol version
- id RequestId - Identifier of the request
mcp: JsonRpcNotification
A notification which does not expect a response.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- jsonrpc JSONRPC_VERSION - The JSON-RPC protocol version
mcp: JsonRpcRequest
A request that expects a response.
Fields
- Fields Included from *Request
- method string
- params record { _meta record { progressToken ProgressToken }, anydata... }
- jsonrpc JSONRPC_VERSION - The JSON-RPC protocol version
- id RequestId - Identifier established by the client that should be returned in the response
mcp: JsonRpcResponse
A successful (non-error) response to a request.
Fields
- jsonrpc JSONRPC_VERSION - The JSON-RPC protocol version
- id RequestId - Identifier of the request
- result ServerResult - The result of the request
mcp: ListToolsRequest
Sent from the client to request a list of tools the server has.
Fields
- Fields Included from *PaginatedRequest
- params record { cursor Cursor }
- method "tools/list" - The method identifier for this request
mcp: ListToolsResult
The server's response to a tools/list request from the client.
Fields
- Fields Included from *PaginatedResult
- nextCursor Cursor
- _meta record { anydata... }
- anydata...
- tools Tool[] - A list of tools available on the server.
mcp: LoggingMessageNotification
Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/message" - The method name for the notification
- params record { level LoggingLevel, logger string, data anydata, _meta record {} } - The parameters for the logging message notification
mcp: Notification
Represents a notification.
Fields
- method string - The method name of the notification
- params? record { _meta record {} } - Additional parameters for the notification
mcp: PaginatedRequest
Represents a paginated request with optional cursor-based pagination.
Fields
- params? record {| cursor Cursor |} - Optional pagination parameters
mcp: PaginatedResult
Result that supports pagination
Fields
- Fields Included from *Result
- _meta record { anydata... }
- anydata...
- nextCursor? Cursor - An opaque token representing the pagination position after the last returned result. If present, there may be more results available.
mcp: PingRequest
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 may be disconnected.
Fields
- Fields Included from *Request
- method string
- params record { _meta record { progressToken ProgressToken }, anydata... }
- method "ping" - The method name
mcp: ProgressNotification
An out-of-band notification used to inform the receiver of a progress update for a long-running request.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/progress" - The method name for the notification
- params record { progressToken ProgressToken, progress int, total int, message string, _meta record {} } - The parameters for the progress notification
mcp: PromptListChangedNotification
An optional notification from the server to the client, informing it that the list of prompts it offers has changed.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/prompts/list_changed" - The JSON-RPC method name for prompt list changed notifications
mcp: ProtocolOptions
Additional initialization options.
Fields
- enforceStrictCapabilities? boolean - Whether to restrict emitted requests to only those that the remote side has indicated that they can handle, through their advertised capabilities. Note that this DOES NOT affect checking of local side capabilities, as it is considered a logic error to mis-specify those. Currently this defaults to false, for backwards compatibility with SDK versions that did not advertise capabilities correctly. In future, this will default to true.
mcp: Request
Represents a generic request in the protocol
Fields
- method string - The method name for the request
- params? record { _meta record {| progressToken ProgressToken |} } - Optional parameters for the request
mcp: ResourceContents
The contents of a specific resource or sub-resource.
Fields
- uri string - The URI of this resource.
- mimeType? string - The MIME type of this resource, if known.
mcp: ResourceListChangedNotification
An optional notification from the server to the client, informing it that the list of resources it can read from has changed.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/resources/list_changed" - The JSON-RPC method name for resource list changed notifications
mcp: ResourceUpdatedNotification
A notification from the server to the client, informing it that a resource has changed and may need to be read again.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/resources/updated" - The JSON-RPC method name for resource updated notifications
- params record { uri string, _meta record {} } - The parameters for the resource updated notification
mcp: Result
Base result type with common fields.
Fields
- _meta? record {} - This result property is reserved by the protocol to allow clients and servers to attach additional metadata to their responses.
mcp: ServerCapabilities
Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.
Fields
- experimental? record { record {}... } - Experimental, non-standard capabilities that the server supports.
- logging? record {} - Present if the server supports sending log messages to the client.
- completions? record {} - Present if the server supports argument autocompletion suggestions.
- prompts? record {| listChanged boolean |} - Present if the server offers any prompt templates.
- tools? record {| listChanged boolean |} - Present if the server offers any tools to call.
mcp: TextContent
Text provided to or from an LLM.
Fields
- 'type "text" - The type of content
- text string - The text content of the message
- annotations? Annotations - Optional annotations for the client
mcp: TextResourceContents
Text resource contents
Fields
- Fields Included from *ResourceContents
- text string - The text of the item. This must only be set if the item can actually be represented as text (not binary data).
mcp: Tool
Definition for a tool the client can call.
Fields
- name string - The name of the tool
- description? string - A human-readable description of the tool This can be used by clients to improve the LLM's understanding of available tools.
- inputSchema record { 'type "object" , properties record { record {}... }, required string[] } - A JSON Schema object defining the expected parameters for the tool.
- annotations? ToolAnnotations - Optional additional tool information.
mcp: ToolAnnotations
Additional properties describing a Tool to clients. NOTE: all properties in ToolAnnotations are hints.
Fields
- title? string - A human-readable title for the tool.
- readOnlyHint? boolean - If true, the tool does not modify its environment. Default: false
- destructiveHint? boolean - If true, the tool may perform destructive updates to its environment.
If false, the tool performs only additive updates.
(This property is meaningful only when
readOnlyHint == false) Default: true
- idempotentHint? boolean - If true, calling the tool repeatedly with the same arguments
will have no additional effect on the its environment.
(This property is meaningful only when
readOnlyHint == false) Default: false
- openWorldHint? boolean - If true, this tool may interact with an "open world" of external entities. If false, the tool's domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not. Default: true
mcp: ToolListChangedNotification
An optional notification from the server to the client, informing it that the list of tools it offers has changed.
Fields
- Fields Included from *Notification
- method string
- params record { _meta record { anydata... }, anydata... }
- method "notifications/tools/list_changed" - The JSON-RPC method name for tool list changed notifications
Errors
mcp: ClientError
Error for failures occurring within client operations.
mcp: ClientInitializationError
Error for failures during client initialization.
mcp: Error
Defines the common base error type for this module.
mcp: HttpClientError
Error for failures during HTTP client operations.
mcp: InvalidMessageTypeError
Error when an invalid message type is received from the server.
mcp: JsonParsingError
Error for JSON parsing failures within SSE event data.
mcp: JsonRpcMessageTransformationError
Error for JSON-RPC message transformation failures during streaming.
mcp: ListToolsError
Error for failures during tool listing operations.
mcp: MalformedResponseError
Error when the server response is malformed or unexpected.
mcp: MissingSseDataError
Error when required data is missing from an SSE event.
mcp: ProtocolVersionError
Error for protocol version negotiation failures.
mcp: ResponseParsingError
Error for failures while parsing HTTP response content.
mcp: SessionOperationError
Error for failures during session operations.
mcp: SseEventStreamError
Error for failures while processing SSE event streams.
mcp: SseStreamEstablishmentError
Error for failures during SSE stream establishment.
mcp: ToolCallError
Error for failures during tool execution operations.
mcp: TransportError
Error for failures during transport operations.
mcp: TypeConversionError
Error for failures converting JSON to JsonRpcMessage.
mcp: UninitializedTransportError
Error for operations attempted before transport initialization.
mcp: UnsupportedContentTypeError
Error for unsupported content types in HTTP responses.
Union types
mcp: JsonRpcMessage
JsonRpcMessage
Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent.
mcp: ProgressToken
ProgressToken
A progress token, used to associate progress notifications with the original request.
mcp: Role
Role
The sender or recipient of messages and data in a conversation.
mcp: LoggingLevel
LoggingLevel
The severity of a log message.
mcp: ClientRequest
ClientRequest
Represents a request sent from the client to the server.
mcp: ClientNotification
ClientNotification
Represents a notification sent from the client to the server.
mcp: ServerNotification
ServerNotification
Represents a notification sent from the server to the client.
mcp: ServerResult
ServerResult
Represents a result sent from the server to the client.
Intersection types
mcp: StreamError
StreamError
Error for failures during streaming operations.
mcp: ServerResponseError
ServerResponseError
Error for invalid or unexpected responses from the server.
mcp: StreamableHttpTransportError
StreamableHttpTransportError
Error for failures during HTTP transport operations.
String types
mcp: Cursor
Cursor
An opaque token used to represent a cursor for pagination.
Simple name reference types
mcp: EmptyResult
EmptyResult
A response that indicates success but carries no data.
mcp: ClientResult
ClientResult
Represents a result sent from the client to the server.
mcp: ServerRequest
ServerRequest
Represents a response sent from the server to the client.