526 lines
18 KiB
Markdown
526 lines
18 KiB
Markdown
---
|
|
title: MCP Client
|
|
description: Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
|
|
---
|
|
|
|
# MCP 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 with optional schema validation
|
|
- Resource access and management
|
|
- Prompt system interactions
|
|
- Optional features like roots management, sampling, and elicitation support
|
|
- Progress tracking for long-running operations
|
|
|
|
!!! tip
|
|
The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO, SSE, and Streamable HTTP client transport implementations without requiring external web frameworks.
|
|
|
|
The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
|
|
See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.
|
|
|
|
The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
|
|
|
|
=== "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
|
|
.elicitation() // Enable elicitation capability
|
|
.build())
|
|
.sampling(request -> new CreateMessageResult(response))
|
|
.elicitation(request -> new ElicitResult(ElicitResult.Action.ACCEPT, content))
|
|
.build();
|
|
|
|
// Initialize connection
|
|
client.initialize();
|
|
|
|
// List available tools
|
|
ListToolsResult tools = client.listTools();
|
|
|
|
// Call a tool
|
|
CallToolResult result = client.callTool(
|
|
CallToolRequest.builder("calculator")
|
|
.arguments(Map.of("operation", "add", "a", 2, "b", 3))
|
|
.build()
|
|
);
|
|
|
|
// List and read resources
|
|
ListResourcesResult resources = client.listResources();
|
|
ReadResourceResult resource = client.readResource(
|
|
ReadResourceRequest.builder("resource://uri").build()
|
|
);
|
|
|
|
// List and use prompts
|
|
ListPromptsResult prompts = client.listPrompts();
|
|
GetPromptResult prompt = client.getPrompt(
|
|
GetPromptRequest.builder("greeting").arguments(Map.of("name", "Spring")).build()
|
|
);
|
|
|
|
// Add/remove roots
|
|
client.addRoot(new Root("file:///path", "description"));
|
|
client.removeRoot("file:///path");
|
|
|
|
// Close client
|
|
client.closeGracefully();
|
|
```
|
|
|
|
=== "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
|
|
.elicitation() // Enable elicitation capability
|
|
.build())
|
|
.sampling(request -> Mono.just(new CreateMessageResult(response)))
|
|
.elicitation(request -> Mono.just(new ElicitResult(ElicitResult.Action.ACCEPT, content)))
|
|
.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);
|
|
}))
|
|
.progressConsumer(progress -> Mono.fromRunnable(() -> {
|
|
logger.info("Progress: {}", progress);
|
|
}))
|
|
.build();
|
|
|
|
// Initialize connection and use features
|
|
client.initialize()
|
|
.flatMap(initResult -> client.listTools())
|
|
.flatMap(tools -> {
|
|
return client.callTool(CallToolRequest.builder("calculator")
|
|
.arguments(Map.of("operation", "add", "a", 2, "b", 3))
|
|
.build());
|
|
})
|
|
.flatMap(result -> {
|
|
return client.listResources()
|
|
.flatMap(resources ->
|
|
client.readResource(ReadResourceRequest.builder("resource://uri").build())
|
|
);
|
|
})
|
|
.flatMap(resource -> {
|
|
return client.listPrompts()
|
|
.flatMap(prompts ->
|
|
client.getPrompt(GetPromptRequest.builder("greeting")
|
|
.arguments(Map.of("name", "Spring"))
|
|
.build())
|
|
);
|
|
})
|
|
.flatMap(prompt -> {
|
|
return client.addRoot(new Root("file:///path", "description"))
|
|
.then(client.removeRoot("file:///path"));
|
|
})
|
|
.doFinally(signalType -> {
|
|
client.closeGracefully().subscribe();
|
|
})
|
|
.subscribe();
|
|
```
|
|
|
|
## Client Transport
|
|
|
|
The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
|
|
|
|
### STDIO
|
|
|
|
Creates transport for process-based communication using stdin/stdout:
|
|
|
|
```java
|
|
ServerParameters params = ServerParameters.builder("npx")
|
|
.args("-y", "@modelcontextprotocol/server-everything", "dir")
|
|
.build();
|
|
McpTransport transport = new StdioClientTransport(params, McpJsonDefaults.getMapper());
|
|
```
|
|
|
|
### Streamable HTTP
|
|
|
|
=== "Streamable HttpClient"
|
|
|
|
Creates a Streamable HTTP client transport for efficient bidirectional communication. Included in the core `mcp` module:
|
|
|
|
```java
|
|
McpTransport transport = HttpClientStreamableHttpTransport
|
|
.builder("http://your-mcp-server")
|
|
.endpoint("/mcp")
|
|
.build();
|
|
```
|
|
|
|
The Streamable HTTP transport supports:
|
|
|
|
- Resumable streams for connection recovery
|
|
- Configurable connect timeout
|
|
- Custom HTTP request customization
|
|
- Multiple protocol version negotiation
|
|
|
|
=== "Streamable WebClient (external)"
|
|
|
|
Creates Streamable HTTP WebClient-based client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
|
|
|
|
```java
|
|
McpTransport transport = WebFluxSseClientTransport
|
|
.builder(WebClient.builder().baseUrl("http://your-mcp-server"))
|
|
.build();
|
|
```
|
|
|
|
### SSE HTTP (Legacy)
|
|
|
|
=== "SSE HttpClient"
|
|
|
|
Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
|
|
|
|
```java
|
|
McpTransport transport = HttpClientSseClientTransport.builder("http://your-mcp-server").build();
|
|
```
|
|
=== "SSE WebClient (external)"
|
|
|
|
Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
|
|
|
|
```java
|
|
WebClient.Builder webClientBuilder = WebClient.builder()
|
|
.baseUrl("http://your-mcp-server");
|
|
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
|
|
```
|
|
|
|
|
|
## Client Capabilities
|
|
|
|
The client can be configured with various capabilities:
|
|
|
|
```java
|
|
var capabilities = ClientCapabilities.builder()
|
|
.roots(true) // Enable filesystem roots support with list changes notifications
|
|
.sampling() // Enable LLM sampling support
|
|
.elicitation() // Enable elicitation support (form and URL modes)
|
|
.build();
|
|
```
|
|
|
|
You can also configure elicitation with specific mode support:
|
|
|
|
```java
|
|
var capabilities = ClientCapabilities.builder()
|
|
.elicitation(true, false) // Enable form-based elicitation, disable URL-based
|
|
.build();
|
|
```
|
|
|
|
### Roots Support
|
|
|
|
Roots define the boundaries of where servers can operate within the filesystem:
|
|
|
|
```java
|
|
// Add a root dynamically
|
|
client.addRoot(new Root("file:///path", "description"));
|
|
|
|
// Remove a root
|
|
client.removeRoot("file:///path");
|
|
|
|
// Notify server of roots changes
|
|
client.rootsListChangedNotification();
|
|
```
|
|
|
|
The roots capability allows servers to:
|
|
|
|
- Request the list of accessible filesystem roots
|
|
- Receive notifications when the roots list changes
|
|
- Understand which directories and files they have access to
|
|
|
|
### Sampling Support
|
|
|
|
Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
|
|
|
|
```java
|
|
// Configure sampling handler
|
|
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
|
|
// Sampling implementation that interfaces with LLM
|
|
return new CreateMessageResult(response);
|
|
};
|
|
|
|
// Create client with sampling support
|
|
var client = McpClient.sync(transport)
|
|
.capabilities(ClientCapabilities.builder()
|
|
.sampling()
|
|
.build())
|
|
.sampling(samplingHandler)
|
|
.build();
|
|
```
|
|
|
|
This capability allows:
|
|
|
|
- Servers to leverage AI capabilities without requiring API keys
|
|
- Clients to maintain control over model access and permissions
|
|
- Support for both text and image-based interactions
|
|
- Optional inclusion of MCP server context in prompts
|
|
|
|
### Elicitation Support
|
|
|
|
Elicitation enables servers to request additional information or user input through the client. This is useful when a server needs clarification or confirmation during an operation:
|
|
|
|
```java
|
|
// Configure form elicitation handler
|
|
Function<ElicitFormRequest, ElicitResult> formElicitationHandler = request -> {
|
|
// Present the request to the user and collect their response
|
|
// The request contains a message and a schema describing the expected input
|
|
Map<String, Object> userResponse = collectUserInput(request.message(), request.requestedSchema());
|
|
return new ElicitResult(ElicitResult.Action.ACCEPT, userResponse);
|
|
};
|
|
|
|
// Configure URL elicitation handler
|
|
Function<ElicitUrlRequest, ElicitResult> urlElicitationHandler = request -> {
|
|
// Prompt the user to visit the URL
|
|
// e.g. openBrowser(request.url());
|
|
return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of());
|
|
};
|
|
|
|
// Create client with elicitation support
|
|
var client = McpClient.sync(transport)
|
|
.capabilities(ClientCapabilities.builder()
|
|
.elicitation(true, true) // enables both form and URL elicitation
|
|
.build())
|
|
.elicitation(formElicitationHandler)
|
|
.urlElicitation(urlElicitationHandler)
|
|
.build();
|
|
```
|
|
|
|
The `ElicitResult` supports three actions:
|
|
|
|
- `ACCEPT` - The user accepted and provided the requested information
|
|
- `DECLINE` - The user declined to provide the information
|
|
- `CANCEL` - The operation was cancelled
|
|
|
|
You can optionally have the client fill in missing values from the schema's `default` declarations before returning an accepted result to the server:
|
|
|
|
```java
|
|
var client = McpClient.sync(transport)
|
|
.applyElicitationDefaults(true) // default is false
|
|
.elicitation(formElicitationHandler)
|
|
.build();
|
|
```
|
|
|
|
When enabled, any keys absent from an accepted `ElicitResult.content` are populated with the `default` values declared in the request's `requestedSchema`.
|
|
|
|
#### URL Elicitation Required Handling
|
|
|
|
When a server requires out-of-band URL elicitation but the client has not negotiated support for it (or the server strictly requires out-of-band handling), the server may return a `URL_ELICITATION_REQUIRED` error during tool execution or prompt retrieval.
|
|
|
|
```java
|
|
try {
|
|
mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
|
|
} catch (McpError e) {
|
|
if (e.getJsonRpcError().code() == McpSchema.ErrorCodes.URL_ELICITATION_REQUIRED) {
|
|
// Extract elicitation requests from the error data
|
|
Map<String, Object> data = (Map<String, Object>) e.getJsonRpcError().data();
|
|
TypeRef<List<McpSchema.ElicitUrlRequest>> typeRef = new TypeRef<>() {};
|
|
var requests = McpJsonDefaults.getMapper()
|
|
.convertValue(data.get("elicitations"), typeRef);
|
|
|
|
for (var req : requests) {
|
|
// handle elicitation requests
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Logging Support
|
|
|
|
The client can register a logging consumer to receive log messages from the server and set the minimum logging level to filter messages:
|
|
|
|
```java
|
|
var mcpClient = McpClient.sync(transport)
|
|
.loggingConsumer(notification -> {
|
|
System.out.println("Received log message: " + notification.data());
|
|
})
|
|
.build();
|
|
|
|
mcpClient.initialize();
|
|
|
|
mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);
|
|
|
|
// Call the tool that sends logging notifications
|
|
CallToolResult result = mcpClient.callTool(CallToolRequest.builder("logging-test").build());
|
|
```
|
|
|
|
Clients can control the minimum logging level they receive through the `mcpClient.setLoggingLevel(level)` request. Messages below the set level will be filtered out.
|
|
Supported logging levels (in order of increasing severity): DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7)
|
|
|
|
### Progress Notifications
|
|
|
|
The client can register a progress consumer to track the progress of long-running operations:
|
|
|
|
```java
|
|
var mcpClient = McpClient.sync(transport)
|
|
.progressConsumer(progress -> {
|
|
System.out.println("Progress: " + progress.progress() + "/" + progress.total());
|
|
})
|
|
.build();
|
|
```
|
|
|
|
## Using MCP Clients
|
|
|
|
### Tool Execution
|
|
|
|
Tools are server-side functions that clients can discover and execute. The MCP client provides methods to list available tools and execute them with specific parameters. Each tool has a unique name and accepts a map of parameters.
|
|
|
|
=== "Sync API"
|
|
|
|
```java
|
|
// List available tools
|
|
ListToolsResult tools = client.listTools();
|
|
|
|
// Call a tool with a CallToolRequest
|
|
CallToolResult result = client.callTool(
|
|
CallToolRequest.builder("calculator")
|
|
.arguments(Map.of(
|
|
"operation", "add",
|
|
"a", 1,
|
|
"b", 2
|
|
))
|
|
.build()
|
|
);
|
|
```
|
|
|
|
=== "Async API"
|
|
|
|
```java
|
|
// List available tools asynchronously
|
|
client.listTools()
|
|
.doOnNext(tools -> tools.tools().forEach(tool ->
|
|
System.out.println(tool.name())))
|
|
.subscribe();
|
|
|
|
// Call a tool asynchronously
|
|
client.callTool(CallToolRequest.builder("calculator")
|
|
.arguments(Map.of(
|
|
"operation", "add",
|
|
"a", 1,
|
|
"b", 2
|
|
))
|
|
.build())
|
|
.subscribe();
|
|
```
|
|
|
|
### Tool Schema Validation and Caching
|
|
|
|
The client supports optional JSON schema validation for tool call results and automatic schema caching:
|
|
|
|
```java
|
|
var client = McpClient.sync(transport)
|
|
.jsonSchemaValidator(myValidator) // Enable schema validation
|
|
.enableCallToolSchemaCaching(true) // Cache tool schemas
|
|
.build();
|
|
```
|
|
|
|
### Resource Access
|
|
|
|
Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
|
|
|
|
=== "Sync API"
|
|
|
|
```java
|
|
// List available resources
|
|
ListResourcesResult resources = client.listResources();
|
|
|
|
// Read a resource
|
|
ReadResourceResult resource = client.readResource(
|
|
ReadResourceRequest.builder("resource://uri").build()
|
|
);
|
|
```
|
|
|
|
=== "Async API"
|
|
|
|
```java
|
|
// List available resources asynchronously
|
|
client.listResources()
|
|
.doOnNext(resources -> resources.resources().forEach(resource ->
|
|
System.out.println(resource.name())))
|
|
.subscribe();
|
|
|
|
// Read a resource asynchronously
|
|
client.readResource(ReadResourceRequest.builder("resource://uri").build())
|
|
.subscribe();
|
|
```
|
|
|
|
### Resource Subscriptions
|
|
|
|
When the server advertises `resources.subscribe` support, clients can subscribe to individual resources and receive a callback whenever the server pushes a `notifications/resources/updated` notification for that URI. The SDK automatically re-reads the resource on notification and delivers the updated contents to the registered consumer.
|
|
|
|
Register a consumer on the client builder, then subscribe/unsubscribe at any time:
|
|
|
|
=== "Sync API"
|
|
|
|
```java
|
|
McpSyncClient client = McpClient.sync(transport)
|
|
.resourcesUpdateConsumer(contents -> {
|
|
// called with the updated resource contents after each notification
|
|
System.out.println("Resource updated: " + contents);
|
|
})
|
|
.build();
|
|
|
|
client.initialize();
|
|
|
|
// Subscribe to a specific resource URI
|
|
client.subscribeResource(McpSchema.SubscribeRequest.builder("custom://resource").build());
|
|
|
|
// ... later, stop receiving updates
|
|
client.unsubscribeResource(McpSchema.UnsubscribeRequest.builder("custom://resource").build());
|
|
```
|
|
|
|
=== "Async API"
|
|
|
|
```java
|
|
McpAsyncClient client = McpClient.async(transport)
|
|
.resourcesUpdateConsumer(contents -> Mono.fromRunnable(() -> {
|
|
System.out.println("Resource updated: " + contents);
|
|
}))
|
|
.build();
|
|
|
|
client.initialize()
|
|
.then(client.subscribeResource(McpSchema.SubscribeRequest.builder("custom://resource").build()))
|
|
.subscribe();
|
|
|
|
// ... later, stop receiving updates
|
|
client.unsubscribeResource(McpSchema.UnsubscribeRequest.builder("custom://resource").build())
|
|
.subscribe();
|
|
```
|
|
|
|
### Prompt System
|
|
|
|
The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns.
|
|
|
|
=== "Sync API"
|
|
|
|
```java
|
|
// List available prompt templates
|
|
ListPromptsResult prompts = client.listPrompts();
|
|
|
|
// Get a prompt with parameters
|
|
GetPromptResult prompt = client.getPrompt(
|
|
GetPromptRequest.builder("greeting").arguments(Map.of("name", "World")).build()
|
|
);
|
|
```
|
|
|
|
=== "Async API"
|
|
|
|
```java
|
|
// List available prompt templates asynchronously
|
|
client.listPrompts()
|
|
.doOnNext(prompts -> prompts.prompts().forEach(prompt ->
|
|
System.out.println(prompt.name())))
|
|
.subscribe();
|
|
|
|
// Get a prompt asynchronously
|
|
client.getPrompt(GetPromptRequest.builder("greeting").arguments(Map.of("name", "World")).build())
|
|
.subscribe();
|
|
```
|