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
See Also:

  • Method Details

    • 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
      • The client's capabilities
      • Client implementation information
      The server MUST respond with its own capabilities and information: McpSchema.ServerCapabilities.
      After successful initialization, the client MUST send an initialized notification to indicate it is ready to begin normal operations.
      Initialization Spec
      Returns:
      the initialize result.

    • 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

    • 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

    • 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.
      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: - name: The name of the tool to call (must match a tool name from tools/list) - arguments: Arguments that conform to the tool's input schema
      Returns:
      A Mono that emits the tool execution result containing: - content: List of content items (text, images, or embedded resources) representing the tool's output - isError: Boolean indicating if the execution failed (true) or succeeded (false/absent)

    • 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 containing: - tools: List of available tools, each with a name, description, and input schema - nextCursor: Optional cursor for pagination if more tools are available

    • 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 containing: - tools: List of available tools, each with a name, description, and input schema - nextCursor: Optional cursor for pagination if more tools are available

    • listResources

      public reactor.core.publisher.Mono<McpSchema.ListResourcesResult> listResources()
      Send a resources/list request.
      Returns:
      A Mono that completes with the list of resources result

    • listResources

      public reactor.core.publisher.Mono<McpSchema.ListResourcesResult> listResources(String cursor)
      Send a resources/list request.
      Parameters:
      cursor - the cursor for pagination
      Returns:
      A Mono that completes with the list of resources result

    • readResource

      public reactor.core.publisher.Mono<McpSchema.ReadResourceResult> readResource(McpSchema.Resource resource)
      Send a resources/read request.
      Parameters:
      resource - the resource to read
      Returns:
      A Mono that completes with the resource content

    • readResource

      public reactor.core.publisher.Mono<McpSchema.ReadResourceResult> readResource(McpSchema.ReadResourceRequest readResourceRequest)
      Send a resources/read request.
      Parameters:
      readResourceRequest - the read resource request
      Returns:
      A Mono that completes with the resource content

    • listResourceTemplates

      public reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates()
      Resource templates allow servers to expose parameterized resources using URI templates. Arguments may be auto-completed through the completion API. Request a list of resource templates the server has.
      Returns:
      A Mono that completes with the list of resource templates result

    • listResourceTemplates

      public reactor.core.publisher.Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor)
      Resource templates allow servers to expose parameterized resources using URI templates. Arguments may be auto-completed through the completion API. Request a list of resource templates the server has.
      Parameters:
      cursor - the cursor for pagination
      Returns:
      A Mono that completes with the list of resource templates result

    • sendResourcesListChanged

      public reactor.core.publisher.Mono<Void> sendResourcesListChanged()
      List Changed Notification. When the list of available resources changes, servers that declared the listChanged capability SHOULD send a notification.
      Returns:
      A Mono that completes when the notification is sent

    • subscribeResource

      public reactor.core.publisher.Mono<Void> subscribeResource(McpSchema.SubscribeRequest subscribeRequest)
      Subscriptions. The protocol supports optional subscriptions to resource changes. Clients can subscribe to specific resources and receive notifications when they change. Send a resources/subscribe request.
      Parameters:
      subscribeRequest - the subscribe request contains the uri of the resource to subscribe to
      Returns:
      A Mono that completes when the subscription is complete

    • unsubscribeResource

      public reactor.core.publisher.Mono<Void> unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest)
      Send a resources/unsubscribe request.
      Parameters:
      unsubscribeRequest - the unsubscribe request contains the uri of the resource to unsubscribe from
      Returns:
      A Mono that completes when the unsubscription is complete

    • listPrompts

      public reactor.core.publisher.Mono<McpSchema.ListPromptsResult> listPrompts()
      List all available prompts.
      Returns:
      A Mono that completes with the list of prompts result

    • listPrompts

      public reactor.core.publisher.Mono<McpSchema.ListPromptsResult> listPrompts(String cursor)
      List all available prompts.
      Parameters:
      cursor - the cursor for pagination
      Returns:
      A Mono that completes with the list of prompts result

    • getPrompt

      public reactor.core.publisher.Mono<McpSchema.GetPromptResult> getPrompt(McpSchema.GetPromptRequest getPromptRequest)
      Get a prompt by its id.
      Parameters:
      getPromptRequest - the get prompt request
      Returns:
      A Mono that completes with the get prompt result

    • promptListChangedNotification

      public reactor.core.publisher.Mono<Void> promptListChangedNotification()
      (Server) An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
      Returns:
      A Mono that completes when the notification is sent

    • setLoggingLevel

      public reactor.core.publisher.Mono<Void> setLoggingLevel(McpSchema.LoggingLevel loggingLevel)
      Client can set the minimum logging level it wants to receive from the server.
      Parameters:
      loggingLevel - the min logging level