Module io.modelcontextprotocol.sdk.mcp
Package 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, Jihoon Kim
See Also:

  • Field Details

  • Method Details

    • getServerCapabilities

      public McpSchema.ServerCapabilities getServerCapabilities()
      Get the server capabilities that define the supported features and functionality.
      Returns:
      The server capabilities

    • getServerInstructions

      public String getServerInstructions()
      Get the server instructions that provide guidance to the client on how to interact with this server.
      Returns:
      The server instructions

    • 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

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • completeCompletion

      public reactor.core.publisher.Mono<McpSchema.CompleteResult> completeCompletion(McpSchema.CompleteRequest completeRequest)
      Sends a completion/complete request to generate value suggestions based on a given reference and argument. This is typically used to provide auto-completion options for user input fields.
      Parameters:
      completeRequest - The request containing the prompt or resource reference and argument for which to generate completions.
      Returns:
      A Mono that completes with the result containing completion suggestions.
      See Also: