MCP Java SDK 客户端介绍

1.客户端功能

MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责与 MCP 服务器建立并管理连接。它实现了该协议的客户端部分，处理以下功能：

  • 协议版本协商，以确保与服务器的兼容性
  • 能力协商，用于确定可用的功能
  • 消息传输与 JSON-RPC 通信
  • 工具发现与执行
  • 资源访问与管理
  • 提示词系统交互
  • 可选功能，例如根目录管理和采样支持

客户端提供同步和异步两种版本的接口

2.SDK安装

implementation("io.modelcontextprotocol.sdk:mcp:0.14.1")

// 选择WebClient传输时引入
implementation("io.modelcontextprotocol.sdk:mcp-spring-webflux:0.14.1")

3.传输层选择

传输层负责处理 MCP 客户端与服务器之间的通信，针对不同使用场景提供多种实现方式。客户端传输层负责管理消息序列化、连接建立以及协议特定的通信模式。

  • STDIO
ServerParameters params = ServerParameters.builder("npx")
    .args("-y", "@modelcontextprotocol/server-everything", "dir")
    .build();
McpTransport transport = new StdioClientTransport(params);
  • HttpClient
// Streamable-HTTP
McpTransport transport = HttpClientStreamableHttpTransport
                            .builder("http://your-mcp-server")
                            .build();
// SSE
McpTransport transport = HttpClientSseClientTransport
                            .builder("http://your-mcp-server")
                            .build();
  • WebClient
// Streamable-HTTP
WebClient.Builder webClientBuilder = WebClient.builder()
                            .baseUrl("http://your-mcp-server");

McpTransport transport = WebClientStreamableHttpTransport
                            .builder(webClientBuilder)
                            .build();

// SSE
WebClient.Builder webClientBuilder = WebClient.builder()
                            .baseUrl("http://your-mcp-server");

McpTransport transport = WebFluxSseClientTransport(webClientBuilder)
                            .builder(webClientBuilder)
                            .build();

上面的5中方式，根据自己的需求选一个，初始化transport变量，下文会用到

4.使用示例

  • 同步接口

// 使用自定义配置创建一个同步客户端
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // 启用根目录（roots）能力
        .sampling()       // 启用根目录（roots）能力
        .elicitation()    // 启用问询（elicitation）能力
        .build())
    .sampling(request -> CreateMessageResult.builder()...build())
    .elicitation(elicitRequest -> ElicitResult.builder()...build())
    .toolsChangeConsumer((List<McpSchema.Tool> tools) -> ...)
    .resourcesChangeConsumer((List<McpSchema.Resource> resources) -> ...)
    .promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> ...)
    .loggingConsumer((LoggingMessageNotification logging) -> ...)
    .progressConsumer((ProgressNotification progress) -> ...)
    .build();

// 初始化连接
client.initialize();

// 列出所有可用工具
ListToolsResult tools = client.listTools();

// 调用一个工具（例如名为 "calculator" 的工具）
CallToolResult result = client.callTool(
    new CallToolRequest("calculator",
        Map.of("operation", "add", "a", 2, "b", 3))
);

//  列出并读取资源
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
    new ReadResourceRequest("resource://uri")
);

// 列出并使用提示模板
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "Spring"))
);

// 添加/移除根目录
client.addRoot(new Root("file:///path", "description"));
client.removeRoot("file:///path");

// 优雅关闭客户端
client.closeGracefully();
  • 异步接口
// 使用自定义配置创建一个异步客户端
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)     
        .sampling()      
        .elicitation()   
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .elicitation(elicitRequest -> Mono.just(ElicitResult.builder()...build()))
    .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)))
    .loggingConsumer(notification -> Mono.fromRunnable(() -> logger.info("Log: {}", notification.data())))
    .progressConsumer(progress -> Mono.fromRunnable(() -> logger.info("Progress update: {}", progress.data())))
    .build();

// 初始化连接并且使用特性
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();

5. 常用设置

5.1 根目录（Roots）

根目录定义了服务器在文件系统中可以操作的边界

// 动态添加根目录
client.addRoot(new Root("file:///path", "description"));

// 删除根目录
client.removeRoot("file:///path");

// 通知服务端根目录变更
client.rootsListChangedNotification();

根目录能力允许服务器：

  • 请求可访问的文件系统根目录列表
  • 在根目录列表发生变化时接收通知
  • 了解它们可以访问哪些目录和文件

5.2 采样（Sampling）

采样功能使服务器能够通过客户端请求大语言模型交互（“补全”或“生成”）：

// 配置采样处理器
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // 与大语言模型接口交互的采样实现
    return new CreateMessageResult(response);
};

// 创建支持采样的客户端
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .sampling()
        .build())
    .sampling(samplingHandler)
    .build();

此功能允许：

  • 服务器利用AI能力而无需要求API密钥
  • 客户端维护对模型访问和权限的控制
  • 支持文本和基于图像的交互
  • 在提示中可选择性地包含MCP服务器上下文

5.3 启发（Elicitation）

启发功能使服务器能够向客户端请求特定信息或说明

// 配置启发处理器
Function<ElicitRequest, ElicitResult> elicitationHandler = request -> {
    // 通过大模型实现启发接口
    return ElicitResult.builder()...build();
};

var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .elicitation() 
        .build())
    .elicitation(elicitationHandler)
    .build();

5.4 日志（Logging）

客户端可以注册一个日志消费者来接收来自服务器的日志消息，并设置最低日志级别以过滤消息

var mcpClient = McpClient.sync(transport)
        .loggingConsumer((LoggingMessageNotification notification) -> {
            System.out.println("Received log message: " + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));

客户端可以通过 mcpClient.setLoggingLevel(level) 请求来控制它们接收的最低日志级别。低于设定级别的消息将被过滤掉。支持的日志级别（按严重程度递增顺序）：DEBUG (0)、INFO (1)、NOTICE (2)、WARNING (3)、ERROR (4)、CRITICAL (5)、ALERT (6)、EMERGENCY (7)

5.5 进度（Progress）

客户端可以注册一个进度消费者来接收来自服务器的进度更新

var mcpClient = McpClient.sync(transport)
        .progressConsumer((ProgressNotification progress) -> {
            System.out.println("Received progress update: " + progress.data());
        })
        .build();

mcpClient.initialize();

CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("progress-test", Map.of()));

5.6 变更通知（Change Notifications）

客户端可以注册一个变更消费者来接收来自服务器的工具、资源或提示更新的变更通知

var spec = McpClient.sync(transport);

// 添加一个消费者，用于在可用工具发生变化（例如工具被添加或移除）时接收通知。
spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
    // Handle tools change
});

// 添加一个消费者，用于在可用资源发生变化（例如资源被添加或移除）时接收通知。
spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
    // Handle resources change
});

// 添加一个消费者，用于在可用提示发生变化（例如提示被添加或移除）时接收通知。
spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
    // Handle prompts change

});

6. 常用方法

6.1 工具执行（Tool Execution）

工具是服务端提供的函数，客户端可以发现并执行它们。MCP 客户端提供了相应方法，用于列出可用的工具，并使用特定参数执行这些工具。每个工具都有一个唯一名称，并接受一个参数映射

  • 同步接口
// 同步列举所有工具
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));

// 同步执行工具
var result = client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 1,
    "b", 2
));
  • 异步接口
// 异步列举所有工具
client.listTools()
    .doOnNext(tools -> tools.forEach(tool ->
        System.out.println(tool.getName())))
    .subscribe();

// 异步执行工具
client.callTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();

6.2 资源访问（Resource Access）

资源代表服务端的数据源，客户端可通过 URI 模板进行访问。MCP 客户端提供了相应方法，用于发现可用的资源，并通过标准化接口获取其内容。

  • 同步接口
// 列举资源
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));

// 使用URI获取资源
var content = client.getResource("file", Map.of(
    "path", "/path/to/file.txt"
));
  • 异步接口
// 列举资源
client.listResources()
    .doOnNext(resources -> resources.forEach(resource ->
        System.out.println(resource.getName())))
    .subscribe();

// 使用URI获取资源
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();

6.3 提示词系统（Prompt System）

提示词系统支持与服务端的提示词模板进行交互。这些模板可以被发现，并通过自定义参数执行，从而基于预定义的模式实现动态文本生成。

  • 同步接口
// 同步列举提示词模板
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

// 通过参数执行提示词
var response = client.executePrompt("echo", Map.of(
    "text", "Hello, World!"
));
  • 异步接口
// 列举提示词模板
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt ->
        System.out.println(prompt.getName())))
    .subscribe();

// 通过参数执行提示词
client.executePrompt("echo", Map.of(
        "text", "Hello, World!"
    ))
    .subscribe();

6.4 使用补全（Using Completion）

作为“补全”能力的一部分，MCP 为服务器提供了一种标准化机制，用于针对提示词和资源 URI 提供参数自动补全建议。

在客户端，MCP 客户端提供了相应的方法用于请求自动补全建议

  • 同步接口
CompleteRequest request = new CompleteRequest(
        new PromptReference("code_review"),
        new CompleteRequest.CompleteArgument("language", "py"));

CompleteResult result = syncMcpClient.completeCompletion(request);
  • 异步接口
CompleteRequest request = new CompleteRequest(
        new PromptReference("code_review"),
        new CompleteRequest.CompleteArgument("language", "py"));

Mono<CompleteResult> result = mcpClient.completeCompletion(request);

6.5 添加上下文信息（Adding Context Information）

通过 SSE 或可流式传输的 HTTP（Streamable HTTP）发送的 HTTP 请求，可通过专用 API 进行定制。这些定制功能，可能需要额外的上下文相关数据，此类数据必须在客户端层面注入。

  • 同步接口

McpSyncClient 用于阻塞式环境中，可能会依赖线程局部变量来共享信息。例如，某些框架会将当前服务器请求或安全令牌存储在线程局部变量中。为了将此类信息传递给底层传输层，请使用SyncSpec#transportContextProvider

McpClient.sync(transport)
    .transportContextProvider(() -> {
        var data = obtainDataFromThreadLocals();
        return McpTransportContext.create(
                Map.of("some-data", data)
        );
    })
    .build();

创建的 McpTransportContext 将在基于 HttpClient 的 McpSyncHttpClientRequestCustomizer 以及基于 WebClient 的 ExchangeFilterFunction中可用。

  • 异步接口

McpAsyncClient 用于响应式环境中，相关信息通过 Reactor上下文在响应式链路中传递。若要在调用客户端操作时向 Reactor 上下文中注入数据，请使用contextWrite

var client = McpClient.async(transport)
    // ...
    .build();

Mono<McpSchema.ListToolsResult> toolList = client
    .listTools()
    .contextWrite(ctx -> {
        var transportContext = McpTransportContext.create(
            Map.of("some-key", "some value")
        );
        return ctx.put(McpTransportContext.KEY, transportContext)
            .put("reactor-context-key", "some reactor value");
    });

通过这种方式，McpTransportContext将可在基于 HttpClient 的 cpAsyncHttpClientRequestCustomizer中获取。此外，整个 Reactor 上下文也可在 McpAsyncHttpClientRequestCustomizer 和 WebClient 的 ExchangeFilterFunction 中通过 Mono.deferContextual 访问

WebClient.builder()
    .filter((request, next) -> {
        return Mono.deferContextual(ctx -> {
            var transportContext = ctx.get(McpTransportContext.KEY);
            var someReactorValue = ctx.get("reactor-context-key");
            // ... 使用变量 ...
        });
    });
# java
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

智能监测与早期风险预测

avatar 2048 AI社区

task04 参数高效微调

本文介绍了参数高效微调(PEFT)技术的背景与发展。随着预训练模型参数规模扩大，全量微调面临计算成本高、存储压力大等问题。研究者提出PEFT技术，仅调整少量参数或添加小型模块来适应下游任务。重点分析了两种PEFT方法：Adapter Tuning通过在Transformer层插入小型适配器模块实现微调；Prefix Tuning则通过添加可训练的前缀激活值来引导模型输出。这些方法显著降低了微调成本

avatar 2048 AI社区
cover

2026本科生必看！10个降AI率工具测评榜单

avatar 2048 AI社区