java-sdk/mintlify-docs/docs/mcp-client.mdx

---
title: MCP Client
description: Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
---

# Model Context Protocol Client

The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:

- Protocol version negotiation to ensure compatibility with servers
- Capability negotiation to determine available features
- Message transport and JSON-RPC communication
- Tool discovery and execution
- Resource access and management
- Prompt system interactions
- Optional features like roots management and sampling support

The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.

<Tabs>
  <Tab title="Sync API">
```java
// Create a sync client with custom configuration
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .build())
    .sampling(request -> new CreateMessageResult(response))
    .build();

// Initialize connection
client.initialize();

// List available tools
ListToolsResult tools = client.listTools();

// Call a tool
CallToolResult result = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "add", "a", 2, "b", 3))
);

// List and read resources
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
    new ReadResourceRequest("resource://uri")
);

// List and use prompts
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "Spring"))
);

// Add/remove roots
client.addRoot(new Root("file:///path", "description"));
client.removeRoot("file:///path");

// Close client
client.closeGracefully();
```
  </Tab>

  <Tab title="Async API">
```java
// Create an async client with custom configuration
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> {
        logger.info("Tools updated: {}", tools);
    }))
    .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> {
        logger.info("Resources updated: {}", resources);
    }))
    .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> {
        logger.info("Prompts updated: {}", prompts);
    }))
    .build();

// Initialize connection and use features
client.initialize()
    .flatMap(initResult -> client.listTools())
    .flatMap(tools -> {
        return client.callTool(new CallToolRequest(
            "calculator", 
            Map.of("operation", "add", "a", 2, "b", 3)
        ));
    })
    .flatMap(result -> {
        return client.listResources()
            .flatMap(resources -> 
                client.readResource(new ReadResourceRequest("resource://uri"))
            );
    })
    .flatMap(resource -> {
        return client.listPrompts()
            .flatMap(prompts ->
                client.getPrompt(new GetPromptRequest(
                    "greeting", 
                    Map.of("name", "Spring")
                ))
            );
    })
    .flatMap(prompt -> {
        return client.addRoot(new Root("file:///path", "description"))
            .then(client.removeRoot("file:///path"));            
    })
    .doFinally(signalType -> {
        client.closeGracefully().subscribe();
    })
    .subscribe();
```
  </Tab>
</Tabs>

## Client Features

### Tool Execution

Tools are server-side functions that can be discovered and executed by clients. The client provides methods to list available tools and execute them with parameters.

<Tabs>
  <Tab title="Sync API">
```java
// List available tools
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));

// Execute a tool
var result = client.executeTool("calculator", Map.of(
    "operation", "add",
    "a", 1,
    "b", 2
));
```
  </Tab>

  <Tab title="Async API">
```java
// List available tools
client.listTools()
    .doOnNext(tools -> tools.forEach(tool -> 
        System.out.println(tool.getName())))
    .subscribe();

// Execute a tool
client.executeTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();
```
  </Tab>
</Tabs>

### Resource Access

Resources are server-side data sources that can be accessed by clients using URI templates. The client provides methods to list available resources and retrieve their content.

<Tabs>
  <Tab title="Sync API">
```java
// List available resources
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));

// Get a resource
var content = client.getResource("file", Map.of(
    "path", "/path/to/file.txt"
));
```
  </Tab>

  <Tab title="Async API">
```java
// List available resources
client.listResources()
    .doOnNext(resources -> resources.forEach(resource -> 
        System.out.println(resource.getName())))
    .subscribe();

// Get a resource
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();
```
  </Tab>
</Tabs>

### Prompt System

The prompt system allows clients to interact with server-side prompt templates. The client provides methods to list available prompts and execute them with parameters.

<Tabs>
  <Tab title="Sync API">
```java
// List available prompts
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

// Execute a prompt
var response = client.executePrompt("echo", Map.of(
    "text", "Hello, World!"
));
```
  </Tab>

  <Tab title="Async API">
```java
// List available prompts
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt -> 
        System.out.println(prompt.getName())))
    .subscribe();

// Execute a prompt
client.executePrompt("echo", Map.of(
        "text", "Hello, World!"
    ))
    .subscribe();
```
  </Tab>
</Tabs>