Module io.modelcontextprotocol.sdk.mcp
Package io.modelcontextprotocol.client

Interface McpClient

public interface McpClient
Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that enables AI models to interact with external tools and resources through a standardized interface.

This class serves as the main entry point for establishing connections with MCP servers, implementing the client-side of the MCP specification. The protocol follows a client-server architecture where:

  • The client (this implementation) initiates connections and sends requests
  • The server responds to requests and provides access to tools and resources
  • Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC 2.0

The class provides factory methods to create either:

  • McpAsyncClient for non-blocking operations with CompletableFuture responses
  • McpSyncClient for blocking operations with direct responses

Example of creating a basic synchronous client: 


 McpClient.sync(transport)
     .requestTimeout(Duration.ofSeconds(5))
     .build();
Example of creating a basic asynchronous client: 

 McpClient.async(transport)
     .requestTimeout(Duration.ofSeconds(5))
     .build();

Example with advanced asynchronous configuration: 


 McpClient.async(transport)
     .requestTimeout(Duration.ofSeconds(10))
     .capabilities(new ClientCapabilities(...))
     .clientInfo(new Implementation("My Client", "1.0.0"))
     .roots(new Root("file://workspace", "Workspace Files"))
     .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> System.out.println("Tools updated: " + tools)))
     .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> System.out.println("Resources updated: " + resources)))
     .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> System.out.println("Prompts updated: " + prompts)))
     .loggingConsumer(message -> Mono.fromRunnable(() -> System.out.println("Log message: " + message)))
     .build();

The client supports:

  • Tool discovery and invocation
  • Resource access and management
  • Prompt template handling
  • Real-time updates through change consumers
  • Custom sampling strategies
  • Structured logging with severity levels

The client supports structured logging through the MCP logging utility:

  • Eight severity levels from DEBUG to EMERGENCY
  • Optional logger name categorization
  • Configurable logging consumers
  • Server-controlled minimum log level
Author:
Christian Tzolov, Dariusz Jędrzejczyk
See Also:

  • Method Details

    • sync

      @Deprecated static McpClient.SyncSpec sync(ClientMcpTransport transport)
      Deprecated.
      This method will be removed in 0.9.0. Use sync(McpClientTransport)
      Start building a synchronous MCP client with the specified transport layer. The synchronous MCP client provides blocking operations. Synchronous clients wait for each operation to complete before returning, making them simpler to use but potentially less performant for concurrent operations. The transport layer handles the low-level communication between client and server using protocols like stdio or Server-Sent Events (SSE).
      Parameters:
      transport - The transport layer implementation for MCP communication. Common implementations include StdioClientTransport for stdio-based communication and SseClientTransport for SSE-based communication.
      Returns:
      A new builder instance for configuring the client
      Throws:
      IllegalArgumentException - if transport is null

    • sync

      static McpClient.SyncSpec sync(McpClientTransport transport)
      Start building a synchronous MCP client with the specified transport layer. The synchronous MCP client provides blocking operations. Synchronous clients wait for each operation to complete before returning, making them simpler to use but potentially less performant for concurrent operations. The transport layer handles the low-level communication between client and server using protocols like stdio or Server-Sent Events (SSE).
      Parameters:
      transport - The transport layer implementation for MCP communication. Common implementations include StdioClientTransport for stdio-based communication and SseClientTransport for SSE-based communication.
      Returns:
      A new builder instance for configuring the client
      Throws:
      IllegalArgumentException - if transport is null

    • async

      @Deprecated static McpClient.AsyncSpec async(ClientMcpTransport transport)
      Deprecated.
      This method will be removed in 0.9.0. Use async(McpClientTransport)
      Start building an asynchronous MCP client with the specified transport layer. The asynchronous MCP client provides non-blocking operations. Asynchronous clients return reactive primitives (Mono/Flux) immediately, allowing for concurrent operations and reactive programming patterns. The transport layer handles the low-level communication between client and server using protocols like stdio or Server-Sent Events (SSE).
      Parameters:
      transport - The transport layer implementation for MCP communication. Common implementations include StdioClientTransport for stdio-based communication and SseClientTransport for SSE-based communication.
      Returns:
      A new builder instance for configuring the client
      Throws:
      IllegalArgumentException - if transport is null

    • async

      static McpClient.AsyncSpec async(McpClientTransport transport)
      Start building an asynchronous MCP client with the specified transport layer. The asynchronous MCP client provides non-blocking operations. Asynchronous clients return reactive primitives (Mono/Flux) immediately, allowing for concurrent operations and reactive programming patterns. The transport layer handles the low-level communication between client and server using protocols like stdio or Server-Sent Events (SSE).
      Parameters:
      transport - The transport layer implementation for MCP communication. Common implementations include StdioClientTransport for stdio-based communication and SseClientTransport for SSE-based communication.
      Returns:
      A new builder instance for configuring the client
      Throws:
      IllegalArgumentException - if transport is null