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:

McpAsyncClient, McpSyncClient, McpTransport

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	McpClient.AsyncSpec Asynchronous client specification.
static class	McpClient.SyncSpec Synchronous client specification.

Method Summary

Modifier and Type	Method and Description
static McpClient.AsyncSpec	async(McpClientTransport transport) Start building an asynchronous MCP client with the specified transport layer.
static McpClient.SyncSpec	sync(McpClientTransport transport) Start building a synchronous MCP client with the specified transport layer.

Method Detail

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

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