Skip to content

ref-client.md

Latest commit

 

History

History
299 lines (240 loc) · 9.14 KB

ref-client.md

File metadata and controls

299 lines (240 loc) · 9.14 KB
Raw

MCP Client Reference

McpClient Factory

org.springframework.ai.mcp.client.McpClient

The McpClient class serves as a factory for creating Model Context Protocol (MCP) clients. It provides the main entry point for establishing connections with MCP servers, offering both synchronous and asynchronous client implementations.

Overview

The client factory uses a builder pattern for flexible configuration, allowing you to customize various aspects of the client including timeout durations, notification handlers, and more.

Client Types

The factory can create two types of clients:

  • McpAsyncClient for non-blocking operations
  • McpSyncClient for blocking operations

Builder Configuration

Basic Usage

McpClient.using(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .sync(); // or .async()

Builder Methods

using(McpTransport transport)
public static Builder using(McpTransport transport)

Start building an MCP client with the specified transport.

requestTimeout(Duration requestTimeout)
public Builder requestTimeout(Duration requestTimeout)

Set the request timeout duration (default is 20 seconds).

capabilities(ClientCapabilities capabilities)
public Builder capabilities(ClientCapabilities capabilities)

Set the client capabilities that define what features the client supports.

clientInfo(Implementation clientInfo)
public Builder clientInfo(Implementation clientInfo)

Set the client implementation information (name and version).

roots(List roots)
public Builder roots(List<Root> roots)

Add a list of roots that define filesystem boundaries for server operations.

roots(Root... roots)
public Builder roots(Root... roots)

Add roots that define filesystem boundaries for server operations.

toolsChangeConsumer(Consumer<List> consumer)
public Builder toolsChangeConsumer(Consumer<List<McpSchema.Tool>> toolsChangeConsumer)

Add a consumer for tool changes notifications.

resourcesChangeConsumer(Consumer<List> consumer)
public Builder resourcesChangeConsumer(Consumer<List<McpSchema.Resource>> resourcesChangeConsumer)

Add a consumer for resource changes notifications.

promptsChangeConsumer(Consumer<List> consumer)
public Builder promptsChangeConsumer(Consumer<List<McpSchema.Prompt>> promptsChangeConsumer)

Add a consumer for prompt changes notifications.

sync()
public McpSyncClient sync()

Build and return a synchronous MCP client.

async()
public McpAsyncClient async()

Build and return an asynchronous MCP client.

Usage Examples

Creating a Synchronous Client

McpTransport transport = // obtain transport instance

// Configure client capabilities
ClientCapabilities capabilities = ClientCapabilities.builder()
    .experimental(Map.of("feature", "value"))
    .roots(true)
    .sampling()
    .build();

McpSyncClient client = McpClient.using(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .rootsListChangedNotification(true)
    .toolsChangeConsumer(tools -> {
        System.out.println("Tools updated: " + tools);
    })
    .sync();

// Initialize client with capabilities
client.initialize(LATEST_PROTOCOL_VERSION, capabilities, 
    new Implementation("client-name", "1.0.0"));

Creating an Asynchronous Client

McpTransport transport = // obtain transport instance
McpAsyncClient client = McpClient.using(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .resourcesChangeConsumer(resources -> {
        System.out.println("Resources updated: " + resources);
    })
    .async();

Using Multiple Change Consumers

McpClient.using(transport)
    .toolsChangeConsumer(tools -> {
        // Handle tool changes
    })
    .toolsChangeConsumer(tools -> {
        // Additional tool change handling
    })
    .resourcesChangeConsumer(resources -> {
        // Handle resource changes
    })
    .sync();

Client Capabilities

The ClientCapabilities class represents features that clients can implement to enrich connected MCP servers. It uses a builder pattern for easy configuration.

ClientCapabilities Builder

ClientCapabilities capabilities = ClientCapabilities.builder()
    .experimental(experimentalMap)
    .roots(true)
    .sampling()
    .build();
Builder Methods
experimental(Map<String, Object> experimental)
public Builder experimental(Map<String, Object> experimental)

Set experimental features map for work-in-progress capabilities.

roots(Boolean listChanged)
public Builder roots(Boolean listChanged)

Configure root capabilities with listChanged parameter. Roots define the boundaries of where servers can operate within the filesystem.

sampling()
public Builder sampling()

Add sampling capabilities that allow servers to request LLM sampling from language models via clients.

Client Operations

Root Management

Both synchronous and asynchronous clients provide methods for managing filesystem roots:

Synchronous API
void addRoot(Root root)                    // Add a new root
void removeRoot(String rootUri)            // Remove a root by URI
void rootsListChangedNotification()        // Notify about roots list changes
Asynchronous API
Mono<Void> addRoot(Root root)             // Add a new root
Mono<Void> removeRoot(String rootUri)      // Remove a root by URI
Mono<Void> rootsListChangedNotification()  // Notify about roots list changes

Tools API

Methods for interacting with server tools:

Synchronous API
CallToolResult callTool(CallToolRequest request)     // Execute a tool
ListToolsResult listTools()                         // List all available tools
ListToolsResult listTools(String cursor)            // List tools with pagination
Asynchronous API
Mono<CallToolResult> callTool(CallToolRequest request)
Mono<ListToolsResult> listTools()
Mono<ListToolsResult> listTools(String cursor)

Resources API

Methods for working with server resources:

Synchronous API
ListResourcesResult listResources()                          // List all resources
ListResourcesResult listResources(String cursor)             // List resources with pagination
ReadResourceResult readResource(Resource resource)           // Read a resource
ReadResourceResult readResource(ReadResourceRequest request) // Read a resource by request
ListResourceTemplatesResult listResourceTemplates()          // List resource templates
void subscribeResource(SubscribeRequest request)            // Subscribe to resource updates
void unsubscribeResource(UnsubscribeRequest request)        // Unsubscribe from updates
void sendResourcesListChanged()                             // Notify about resource changes
Asynchronous API
Mono<ListResourcesResult> listResources()
Mono<ListResourcesResult> listResources(String cursor)
Mono<ReadResourceResult> readResource(Resource resource)
Mono<ReadResourceResult> readResource(ReadResourceRequest request)
Mono<ListResourceTemplatesResult> listResourceTemplates()
Mono<Void> subscribeResource(SubscribeRequest request)
Mono<Void> unsubscribeResource(UnsubscribeRequest request)
Mono<Void> sendResourcesListChanged()

Prompts API

Methods for working with server prompts:

Synchronous API
ListPromptsResult listPrompts()                        // List all prompts
ListPromptsResult listPrompts(String cursor)           // List prompts with pagination
GetPromptResult getPrompt(GetPromptRequest request)    // Get a specific prompt
void promptListChangedNotification()                   // Notify about prompt changes
Asynchronous API
Mono<ListPromptsResult> listPrompts()
Mono<ListPromptsResult> listPrompts(String cursor)
Mono<GetPromptResult> getPrompt(GetPromptRequest request)
Mono<Void> promptListChangedNotification()

Lifecycle Management

Methods for managing client lifecycle:

Synchronous API
InitializeResult initialize()     // Initialize client connection
void close()                     // Close client immediately
boolean closeGracefully()        // Close client with graceful shutdown
Object ping()                    // Send ping request
Asynchronous API
Mono<InitializeResult> initialize()
void close()
Mono<Void> closeGracefully()
Mono<Object> ping()

Implementation Notes

  • The client factory uses a builder pattern for configuration
  • Default request timeout is 20 seconds
  • Multiple consumers can be registered for tools, resources, and prompts changes
  • The builder validates that the transport is not null
  • Deprecated static factory methods are available but using the builder pattern is recommended
  • The synchronous client is implemented as a wrapper around the asynchronous client
  • ClientCapabilities uses a builder pattern for configuring client features
  • The synchronous client blocks on async operations with the configured request timeout
  • Resource subscriptions require server support for the subscribe capability
  • Root management requires client to be configured with root capabilities