> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Java MCP 客户端

> 学习如何使用模型上下文协议（MCP）客户端与 MCP 服务器进行交互

前往 [Java MCP 服务器](/sdk/java/mcp-server) 学习如何构建 MCP 服务器，或者前往 [Java MCP 概述](/sdk/java/mcp-overview) 了解整体架构。

# 模型上下文协议客户端

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

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

<Tip>
  核心 `io.modelcontextprotocol.sdk:mcp` 模块提供了无需外部 Web 框架的 STDIO 和 SSE 客户端传输实现。

  对于 [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) 用户，可选依赖 `io.modelcontextprotocol.sdk:mcp-spring-webflux` 提供了基于 Spring 的特定传输实现。
</Tip>

<Tip>
  这个基于 Spring AI MCP 的 [快速入门演示](/quickstart/client) 将向您展示如何构建连接到 MCP 服务器的 AI 客户端。
</Tip>

客户端提供了同步和异步 API，以适应不同应用场景的灵活性。

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}
    // 创建具有自定义配置的同步客户端
    McpSyncClient client = McpClient.sync(transport)
        .requestTimeout(Duration.ofSeconds(10))
        .capabilities(ClientCapabilities.builder()
            .roots(true)      // 启用根目录能力
            .sampling()       // 启用采样能力
            .build())
        .sampling(request -> new CreateMessageResult(response))
        .build();

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

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

    // 调用工具
    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();
    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}
    // 创建具有自定义配置的异步客户端
    McpAsyncClient client = McpClient.async(transport)
        .requestTimeout(Duration.ofSeconds(10))
        .capabilities(ClientCapabilities.builder()
            .roots(true)      // 启用根目录能力
            .sampling()       // 启用采样能力
            .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();

    // 初始化连接并使用功能
    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>

## 客户端传输

传输层处理 MCP 客户端与服务器之间的通信，为各种用例提供不同的实现。客户端传输管理消息序列化、连接建立和协议特定的通信模式。

<Tabs>
  <Tab title="STDIO">
    创建用于进程内通信的传输

    ```java theme={null}
    ServerParameters params = ServerParameters.builder("npx")
        .args("-y", "@modelcontextprotocol/server-everything", "dir")
        .build();
    McpTransport transport = new StdioClientTransport(params);
    ```
  </Tab>

  <Tab title="SSE (HttpClient)">
    创建与框架无关（纯 Java API）的 SSE 客户端传输。包含在核心 mcp 模块中。

    ```java theme={null}
    McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
    ```
  </Tab>

  <Tab title="SSE (WebFlux)">
    创建基于 WebFlux 的 SSE 客户端传输。需要 mcp-webflux-sse-transport 依赖。

    ```java theme={null}
    WebClient.Builder webClientBuilder = WebClient.builder()
        .baseUrl("http://your-mcp-server");
    McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
    ```
  </Tab>
</Tabs>

## 客户端能力

客户端可以配置各种能力：

```java theme={null}
var capabilities = ClientCapabilities.builder()
    .roots(true)      // 启用带有列表变更通知的文件系统根目录支持
    .sampling()       // 启用 LLM 采样支持
    .build();
```

### 根目录支持

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

```java theme={null}
// 动态添加根目录
client.addRoot(new Root("file:///path", "description"));

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

// 通知服务器根目录列表变更
client.rootsListChangedNotification();
```

根目录能力允许服务器：

* 请求可访问的文件系统根目录列表
* 接收根目录列表变更的通知
* 了解其可以访问的目录和文件

### 采样支持

采样使服务器能够通过客户端请求 LLM 交互（“补全”或“生成”）：

```java theme={null}
// 配置采样处理器
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // 与 LLM 接口的采样实现
    return new CreateMessageResult(response);
};

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

此能力允许：

* 服务器利用 AI 能力而无需 API 密钥
* 客户端控制模型访问和权限
* 支持文本和图像交互
* 在提示中可选包含 MCP 服务器上下文

### 日志支持

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

```java theme={null}
var mcpClient = McpClient.sync(transport)
        .loggingConsumer(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）

## 使用 MCP 客户端

### 工具执行

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

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}
    // 列出可用工具及其名称
    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
    ));
    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}
    // 异步列出可用工具
    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();
    ```
  </Tab>
</Tabs>

### 资源访问

资源代表客户端可以通过 URI 模板访问的服务器端数据源。MCP 客户端提供通过标准化接口发现可用资源并检索其内容的方法。

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}
    // 列出可用资源及其名称
    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"
    ));
    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}
    // 异步列出可用资源
    client.listResources()
        .doOnNext(resources -> resources.forEach(resource ->
            System.out.println(resource.getName())))
        .subscribe();

    // 异步检索资源内容
    client.getResource("file", Map.of(
            "path", "/path/to/file.txt"
        ))
        .subscribe();
    ```
  </Tab>
</Tabs>

### 提示系统

提示系统允许与服务器端提示模板交互。这些模板可以被发现并使用自定义参数执行，从而根据预定义模式生成动态文本。

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}
    // 列出可用提示模板
    var prompts = client.listPrompts();
    prompts.forEach(prompt -> System.out.println(prompt.getName()));

    // 使用参数执行提示模板
    var response = client.executePrompt("echo", Map.of(
        "text", "Hello, World!"
    ));
    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}
    // 异步列出可用提示模板
    client.listPrompts()
        .doOnNext(prompts -> prompts.forEach(prompt ->
            System.out.println(prompt.getName())))
        .subscribe();

    // 异步执行提示模板
    client.executePrompt("echo", Map.of(
            "text", "Hello, World!"
        ))
        .subscribe();
    ```
  </Tab>
</Tabs>

### 使用补全

作为 [补全能力](/specification/2025-03-26/server/utilities/completion) 的一部分，MCP 提供了标准化方式，使服务器可以为提示和资源 URI 提供参数自动补全建议。

请查看 [服务器补全能力](/sdk/java/mcp-server#completion-specification) 以了解如何在服务器端启用和配置补全功能。

在客户端方面，MCP 客户端提供请求自动补全的方法：

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}

    CompleteRequest request = new CompleteRequest(
            new PromptReference("code_review"),
            new CompleteRequest.CompleteArgument("language", "py"));

    CompleteResult result = syncMcpClient.completeCompletion(request);

    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}

    CompleteRequest request = new CompleteRequest(
            new PromptReference("code_review"),
            new CompleteRequest.CompleteArgument("language", "py"));

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

    ```
  </Tab>
</Tabs>