io.modelcontextprotocol.client

Class McpAsyncClient

java.lang.Object

io.modelcontextprotocol.client.McpAsyncClient

public class McpAsyncClient
extends Object

The Model Context Protocol (MCP) client implementation that provides asynchronous communication with MCP servers using Project Reactor's Mono and Flux types.

This client implements the MCP specification, enabling AI models to interact with external tools and resources through a standardized interface. Key features include:

• Asynchronous communication using reactive programming patterns
• Tool discovery and invocation for server-provided functionality
• Resource access and management with URI-based addressing
• Prompt template handling for standardized AI interactions
• Real-time notifications for tools, resources, and prompts changes
• Structured logging with configurable severity levels
• Message sampling for AI model interactions

The client follows a lifecycle:

1. Initialization - Establishes connection and negotiates capabilities
2. Normal Operation - Handles requests and notifications
3. Graceful Shutdown - Ensures clean connection termination

This implementation uses Project Reactor for non-blocking operations, making it suitable for high-throughput scenarios and reactive applications. All operations return Mono or Flux types that can be composed into reactive pipelines.

Author:

Dariusz Jędrzejczyk, Christian Tzolov

See Also:

McpClient, McpSchema, McpClientSession

Field Summary

Fields

Modifier and Type	Field and Description
protected reactor.core.publisher.Sinks.One<McpSchema.InitializeResult>	initializedSink

Method Summary

Modifier and Type	Method and Description
reactor.core.publisher.Mono<Void>	addRoot(McpSchema.Root root) Adds a new root to the client's root list.
reactor.core.publisher.Mono<McpSchema.CallToolResult>	callTool(McpSchema.CallToolRequest callToolRequest) Calls a tool provided by the server.
void	close() Closes the client connection immediately.
reactor.core.publisher.Mono<Void>	closeGracefully() Gracefully closes the client connection.
McpSchema.ClientCapabilities	getClientCapabilities() Get the client capabilities that define the supported features and functionality.
McpSchema.Implementation	getClientInfo() Get the client implementation information.
reactor.core.publisher.Mono<McpSchema.GetPromptResult>	getPrompt(McpSchema.GetPromptRequest getPromptRequest) Retrieves a specific prompt by its ID.
McpSchema.ServerCapabilities	getServerCapabilities() Get the server capabilities that define the supported features and functionality.
McpSchema.Implementation	getServerInfo() Get the server implementation information.
reactor.core.publisher.Mono<McpSchema.InitializeResult>	initialize() The initialization phase MUST be the first interaction between client and server.
boolean	isInitialized() Check if the client-server connection is initialized.
reactor.core.publisher.Mono<McpSchema.ListPromptsResult>	listPrompts() Retrieves the list of all prompts provided by the server.
reactor.core.publisher.Mono<McpSchema.ListPromptsResult>	listPrompts(String cursor) Retrieves a paginated list of prompts provided by the server.
reactor.core.publisher.Mono<McpSchema.ListResourcesResult>	listResources() Retrieves the list of all resources provided by the server.
reactor.core.publisher.Mono<McpSchema.ListResourcesResult>	listResources(String cursor) Retrieves a paginated list of resources provided by the server.
reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult>	listResourceTemplates() Retrieves the list of all resource templates provided by the server.
reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult>	listResourceTemplates(String cursor) Retrieves a paginated list of resource templates provided by the server.
reactor.core.publisher.Mono<McpSchema.ListToolsResult>	listTools() Retrieves the list of all tools provided by the server.
reactor.core.publisher.Mono<McpSchema.ListToolsResult>	listTools(String cursor) Retrieves a paginated list of tools provided by the server.
void	openSSE() The client may issue an HTTP GET to the MCP endpoint.
reactor.core.publisher.Mono<Object>	ping() Sends a ping request to the server.
reactor.core.publisher.Mono<McpSchema.ReadResourceResult>	readResource(McpSchema.ReadResourceRequest readResourceRequest) Reads the content of a specific resource identified by the provided request.
reactor.core.publisher.Mono<McpSchema.ReadResourceResult>	readResource(McpSchema.Resource resource) Reads the content of a specific resource identified by the provided Resource object.
reactor.core.publisher.Mono<Void>	removeRoot(String rootUri) Removes a root from the client's root list.
reactor.core.publisher.Mono<Void>	rootsListChangedNotification() Manually sends a roots/list_changed notification.
reactor.core.publisher.Mono<Void>	setLoggingLevel(McpSchema.LoggingLevel loggingLevel) Sets the minimum logging level for messages received from the server.
reactor.core.publisher.Mono<Void>	subscribeResource(McpSchema.SubscribeRequest subscribeRequest) Subscribes to changes in a specific resource.
reactor.core.publisher.Mono<Void>	unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest) Cancels an existing subscription to a resource.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

initializedSink

protected final reactor.core.publisher.Sinks.One<McpSchema.InitializeResult> initializedSink

Method Detail

getServerCapabilities

public McpSchema.ServerCapabilities getServerCapabilities()

Get the server capabilities that define the supported features and functionality.

Returns:

The server capabilities

getServerInfo

public McpSchema.Implementation getServerInfo()

Get the server implementation information.

Returns:

The server implementation details

isInitialized

public boolean isInitialized()

Check if the client-server connection is initialized.

Returns:

true if the client-server connection is initialized

getClientCapabilities

public McpSchema.ClientCapabilities getClientCapabilities()

Get the client capabilities that define the supported features and functionality.

Returns:

The client capabilities

getClientInfo

public McpSchema.Implementation getClientInfo()

Get the client implementation information.

Returns:

The client implementation details

close

public void close()

Closes the client connection immediately.

closeGracefully

public reactor.core.publisher.Mono<Void> closeGracefully()

Gracefully closes the client connection.

Returns:

A Mono that completes when the connection is closed

openSSE

public void openSSE()

The client may issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream, allowing the server to communicate to the client, without the client first sending data via HTTP POST.

initialize

public reactor.core.publisher.Mono<McpSchema.InitializeResult> initialize()

The initialization phase MUST be the first interaction between client and server. During this phase, the client and server:

• Establish protocol version compatibility
• Exchange and negotiate capabilities
• Share implementation details

The client MUST initiate this phase by sending an initialize request containing: The protocol version the client supports, client's capabilities and clients implementation information.

The server MUST respond with its own capabilities and information.

After successful initialization, the client MUST send an initialized notification to indicate it is ready to begin normal operations.

Returns:

the initialize result.

See Also:

MCP Initialization Spec

ping

public reactor.core.publisher.Mono<Object> ping()

Sends a ping request to the server.

Returns:

A Mono that completes with the server's ping response

addRoot

public reactor.core.publisher.Mono<Void> addRoot(McpSchema.Root root)

Adds a new root to the client's root list.

Parameters:

root - The root to add.

Returns:

A Mono that completes when the root is added and notifications are sent.

removeRoot

public reactor.core.publisher.Mono<Void> removeRoot(String rootUri)

Removes a root from the client's root list.

Parameters:

rootUri - The URI of the root to remove.

Returns:

A Mono that completes when the root is removed and notifications are sent.

rootsListChangedNotification

public reactor.core.publisher.Mono<Void> rootsListChangedNotification()

Manually sends a roots/list_changed notification. The addRoot and removeRoot methods automatically send the roots/list_changed notification if the client is in an initialized state.

Returns:

A Mono that completes when the notification is sent.

callTool

public reactor.core.publisher.Mono<McpSchema.CallToolResult> callTool(McpSchema.CallToolRequest callToolRequest)

Calls a tool provided by the server. Tools enable servers to expose executable functionality that can interact with external systems, perform computations, and take actions in the real world.

Parameters:

callToolRequest - The request containing the tool name and input parameters.

Returns:

A Mono that emits the result of the tool call, including the output and any errors.

See Also:

McpSchema.CallToolRequest, McpSchema.CallToolResult, listTools()

listTools

public reactor.core.publisher.Mono<McpSchema.ListToolsResult> listTools()

Retrieves the list of all tools provided by the server.

Returns:

A Mono that emits the list of tools result.

listTools

public reactor.core.publisher.Mono<McpSchema.ListToolsResult> listTools(String cursor)

Retrieves a paginated list of tools provided by the server.

Parameters:

cursor - Optional pagination cursor from a previous list request

Returns:

A Mono that emits the list of tools result

listResources

public reactor.core.publisher.Mono<McpSchema.ListResourcesResult> listResources()

Retrieves the list of all resources provided by the server. Resources represent any kind of UTF-8 encoded data that an MCP server makes available to clients, such as database records, API responses, log files, and more.

Returns:

A Mono that completes with the list of resources result.

See Also:

McpSchema.ListResourcesResult, readResource(McpSchema.Resource)

listResources

public reactor.core.publisher.Mono<McpSchema.ListResourcesResult> listResources(String cursor)

Retrieves a paginated list of resources provided by the server. Resources represent any kind of UTF-8 encoded data that an MCP server makes available to clients, such as database records, API responses, log files, and more.

Parameters:

cursor - Optional pagination cursor from a previous list request.

Returns:

A Mono that completes with the list of resources result.

See Also:

McpSchema.ListResourcesResult, readResource(McpSchema.Resource)

readResource

public reactor.core.publisher.Mono<McpSchema.ReadResourceResult> readResource(McpSchema.Resource resource)

Reads the content of a specific resource identified by the provided Resource object. This method fetches the actual data that the resource represents.

Parameters:

resource - The resource to read, containing the URI that identifies the resource.

Returns:

A Mono that completes with the resource content.

See Also:

McpSchema.Resource, McpSchema.ReadResourceResult

readResource

public reactor.core.publisher.Mono<McpSchema.ReadResourceResult> readResource(McpSchema.ReadResourceRequest readResourceRequest)

Reads the content of a specific resource identified by the provided request. This method fetches the actual data that the resource represents.

Parameters:

readResourceRequest - The request containing the URI of the resource to read

Returns:

A Mono that completes with the resource content.

See Also:

McpSchema.ReadResourceRequest, McpSchema.ReadResourceResult

listResourceTemplates

public reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates()

Retrieves the list of all resource templates provided by the server. Resource templates allow servers to expose parameterized resources using URI templates, enabling dynamic resource access based on variable parameters.

Returns:

A Mono that completes with the list of resource templates result.

See Also:

McpSchema.ListResourceTemplatesResult

listResourceTemplates

public reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor)

Retrieves a paginated list of resource templates provided by the server. Resource templates allow servers to expose parameterized resources using URI templates, enabling dynamic resource access based on variable parameters.

Parameters:

cursor - Optional pagination cursor from a previous list request.

Returns:

A Mono that completes with the list of resource templates result.

See Also:

McpSchema.ListResourceTemplatesResult

subscribeResource

public reactor.core.publisher.Mono<Void> subscribeResource(McpSchema.SubscribeRequest subscribeRequest)

Subscribes to changes in a specific resource. When the resource changes on the server, the client will receive notifications through the resources change notification handler.

Parameters:

subscribeRequest - The subscribe request containing the URI of the resource.

Returns:

A Mono that completes when the subscription is complete.

See Also:

McpSchema.SubscribeRequest, unsubscribeResource(McpSchema.UnsubscribeRequest)

unsubscribeResource

public reactor.core.publisher.Mono<Void> unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest)

Cancels an existing subscription to a resource. After unsubscribing, the client will no longer receive notifications when the resource changes.

Parameters:

unsubscribeRequest - The unsubscribe request containing the URI of the resource.

Returns:

A Mono that completes when the unsubscription is complete.

See Also:

McpSchema.UnsubscribeRequest, subscribeResource(McpSchema.SubscribeRequest)

listPrompts

public reactor.core.publisher.Mono<McpSchema.ListPromptsResult> listPrompts()

Retrieves the list of all prompts provided by the server.

Returns:

A Mono that completes with the list of prompts result.

See Also:

McpSchema.ListPromptsResult, #getPrompt(GetPromptRequest)

listPrompts

public reactor.core.publisher.Mono<McpSchema.ListPromptsResult> listPrompts(String cursor)

Retrieves a paginated list of prompts provided by the server.

Parameters:

cursor - Optional pagination cursor from a previous list request

Returns:

A Mono that completes with the list of prompts result.

See Also:

McpSchema.ListPromptsResult, #getPrompt(GetPromptRequest)

getPrompt

public reactor.core.publisher.Mono<McpSchema.GetPromptResult> getPrompt(McpSchema.GetPromptRequest getPromptRequest)

Retrieves a specific prompt by its ID. This provides the complete prompt template including all parameters and instructions for generating AI content.

Parameters:

getPromptRequest - The request containing the ID of the prompt to retrieve.

Returns:

A Mono that completes with the prompt result.

See Also:

McpSchema.GetPromptRequest, McpSchema.GetPromptResult, listPrompts()

setLoggingLevel

public reactor.core.publisher.Mono<Void> setLoggingLevel(McpSchema.LoggingLevel loggingLevel)

Sets the minimum logging level for messages received from the server. The client will only receive log messages at or above the specified severity level.

Parameters:

loggingLevel - The minimum logging level to receive.

Returns:

A Mono that completes when the logging level is set.

See Also:

McpSchema.LoggingLevel