类class io.agentscope.core.tool.mcp 2.x

McpClientBuilder

public class McpClientBuilder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:95–885

McpClientBuilder 构造 MCP 客户端，支持 STDIO、SSE 与 Streamable HTTP 传输，并可统一设置请求头、查询参数与超时。构造出的客户端可直接注册进工具包。位于 io.agentscope.core.tool.mcp 包。核心成员包括 create、stdioTransport、sseTransport、customizeSseClient、streamableHttpTransport、customizeStreamableHttpClient。

Builder for creating MCP client wrappers with fluent configuration.

Supports three transport types:

StdIO - for local process communication
SSE - for HTTP Server-Sent Events (stateful)
StreamableHTTP - for HTTP streaming (stateless)

Example usage:

`// StdIO transport
McpClientWrapper client = McpClientBuilder.create("git-mcp")
.stdioTransport("python", "-m", "mcp_server_git")
.buildAsync()
.block();

// SSE transport with headers and query parameters
McpClientWrapper client = McpClientBuilder.create("remote-mcp")
.sseTransport("https://mcp.example.com/sse")
.header("Authorization", "Bearer " + token)
.queryParam("queryKey", "queryValue")
.timeout(Duration.ofSeconds(60))
.buildAsync()
.block();

// HTTP transport with multiple query parameters
McpClientWrapper client = McpClientBuilder.create("http-mcp")
.streamableHttpTransport("https://mcp.example.com/http")
.queryParams(Map.of("token", "abc123", "env", "prod"))
.buildSync();

// StdIO transport with custom protocol versions
McpClientWrapper client = McpClientBuilder.create("mcp")
.stdioTransport("python", "server.py")
.protocolVersions("2024-11-05", "2025-03-26")
.buildAsync()
.block();
`

核心精讲Deep dive

McpClientBuilder：接入 MCPMcpClientBuilder: connect MCP

McpClientBuilder 构造 MCP 客户端，支持 STDIO、SSE 与 Streamable HTTP 传输，并可统一设置请求头、查询参数与超时。构造出的客户端可直接注册进 Toolkit。

McpClientBuilder creates MCP clients over STDIO, SSE or Streamable HTTP, with common headers, query parameters and timeouts. The resulting client registers directly into a Toolkit.

create(name) 开始构建，stdioTransport 或 streamableHttpTransport 选择传输。create(name) starts the builder; choose a transport with stdioTransport or streamableHttpTransport.
buildSync 适合启动阶段，buildAsync 返回 Mono 以便非阻塞初始化。buildSync suits startup, while buildAsync returns a Mono for non-blocking initialization.
Toolkit.registerMcpClient 合并工具，closeMcpClients 统一释放连接。Toolkit.registerMcpClient merges tools, and closeMcpClients releases connections together.

连接文件系统 MCP 并注册工具Connect the filesystem MCP and register tools

import io.agentscope.core.tool.Toolkit;
import io.agentscope.core.tool.mcp.McpClientBuilder;
import io.agentscope.core.tool.mcp.McpClientWrapper;

public class McpDemo {
    public static void main(String[] args) {
        McpClientWrapper client = McpClientBuilder.create("filesystem")
                .stdioTransport(
                        "npx",
                        "-y",
                        "@modelcontextprotocol/server-filesystem",
                        ".")
                .buildSync();

        Toolkit toolkit = new Toolkit();
        toolkit.registerMcpClient(client).block();
        System.out.println(toolkit.getToolNames());

        // 智能体使用完毕后统一释放
        toolkit.closeMcpClients();
    }
}

方法摘要Method Summary

方法Method	说明Description
`public static` `McpClientBuilder create(String name)` static	以名称开始构建 MCP 客户端。 Creates a new MCP client builder with the specified name.
`public` `McpClientBuilder stdioTransport(String command, String... args)`	使用 STDIO 传输并指定启动命令。 Configures StdIO transport for local process communication.
`public` `McpClientBuilder stdioTransport(String command, List<String> args, Map<String, String> env)`	使用 STDIO 传输并指定启动命令。 Configures StdIO transport with environment variables.
`public` `McpClientBuilder sseTransport(String url)`	使用 SSE 传输并指定 URL。 Configures HTTP SSE (Server-Sent Events) transport for stateful connections.
`public` `McpClientBuilder customizeSseClient(Consumer<HttpClient.Builder> customizer)`	设置该配置项。 Customizes the HTTP client for SSE transport (only applicable after calling sseTransport).
`public` `McpClientBuilder streamableHttpTransport(String url)`	使用 Streamable HTTP 传输并指定 URL。 Configures HTTP StreamableHTTP transport for stateless connections.
`public` `McpClientBuilder customizeStreamableHttpClient(Consumer<HttpClient.Builder> customizer)`	设置该配置项。 Customizes the HTTP client for StreamableHTTP transport (only applicable after calling streamableHttpTransport).
`public` `McpClientBuilder httpRequestCustomizer(McpSyncHttpClientRequestCustomizer customizer)`	设置该配置项。 Registers a per-request HTTP customizer for dynamic request modification (only applicable for HTTP transports: SSE and StreamableHTTP).
`public` `McpClientBuilder header(String key, String value)`	添加请求头。 Adds an HTTP header (only applicable for HTTP transports).
`public` `McpClientBuilder headers(Map<String, String> headers)`	设置请求头。 Sets multiple HTTP headers (only applicable for HTTP transports).
`public` `McpClientBuilder queryParam(String key, String value)`	设置查询参数。 Adds a query parameter to the URL (only applicable for HTTP transports).
`public` `McpClientBuilder queryParams(Map<String, String> queryParams)`	设置查询参数。 Sets multiple query parameters (only applicable for HTTP transports).
`public` `McpClientBuilder timeout(Duration timeout)`	设置请求超时时长。 Sets the request timeout duration.
`public` `McpClientBuilder initializationTimeout(Duration timeout)`	设置该配置项。 Sets the initialization timeout duration.
`public` `McpClientBuilder protocolVersions(String... versions)`	设置该配置项。 Sets the MCP protocol versions that the client supports.
`public` `McpClientBuilder asyncElicitation(Function<ElicitRequest, Mono<ElicitResult>> handler)`	设置该配置项。 Registers an asynchronous elicitation handler for processing elicit requests from the server.
`public` `McpClientBuilder syncElicitation(Function<ElicitRequest, ElicitResult> handler)`	设置该配置项。 Registers a synchronous elicitation handler for processing elicit requests from the server.
`public` `McpClientBuilder propagateMeta(boolean propagateMeta)`	设置该配置项。 Configures whether request metadata is propagated to this MCP server.
`public Mono<McpClientWrapper> buildAsync()`	异步构建并初始化客户端。 Builds an asynchronous MCP client wrapper.
`public` `McpClientWrapper buildSync()`	同步构建并初始化客户端。 Builds a synchronous MCP client wrapper (blocking operations).

方法详情Method Detail

create

public static McpClientBuilder create(String name)

static

创建并返回实例。

Creates a new MCP client builder with the specified name.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。unique identifier for the MCP client

返回Returns McpClientBuilder

返回McpClientBuilder。new builder instance

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:119–124

stdioTransport

public McpClientBuilder stdioTransport(String command, String... args)

设置该配置项。

Configures StdIO transport for local process communication.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。the executable command
`args` varargs	String...	参数（类型 `String...`）。command arguments

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:133–136

stdioTransport

public McpClientBuilder stdioTransport(String command, List<String> args, Map<String, String> env)

设置该配置项。

Configures StdIO transport with environment variables.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。the executable command
`args`	List<String>	参数（类型 `List`）。command arguments list
`env`	Map<String, String>	env（类型 `Map`）。environment variables

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:146–150

sseTransport

public McpClientBuilder sseTransport(String url)

设置SSE 传输层。

Configures HTTP SSE (Server-Sent Events) transport for stateful connections.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务端 URL。the server URL

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:158–161

customizeSseClient

public McpClientBuilder customizeSseClient(Consumer<HttpClient.Builder> customizer)

设置该配置项。

Customizes the HTTP client for SSE transport (only applicable after calling sseTransport).

参数Parameters

名称Name	类型Type	说明Description
`customizer`	Consumer<HttpClient.Builder>	customizer（类型 `Consumer`）。consumer to customize the HttpClient.Builder

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:180–185

streamableHttpTransport

public McpClientBuilder streamableHttpTransport(String url)

设置该配置项。

Configures HTTP StreamableHTTP transport for stateless connections.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务端 URL。the server URL

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:193–196

customizeStreamableHttpClient

public McpClientBuilder customizeStreamableHttpClient(Consumer<HttpClient.Builder> customizer)

设置该配置项。

Customizes the HTTP client for StreamableHTTP transport (only applicable after calling streamableHttpTransport).

参数Parameters

名称Name	类型Type	说明Description
`customizer`	Consumer<HttpClient.Builder>	customizer（类型 `Consumer`）。consumer to customize the HttpClient.Builder

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:219–224

httpRequestCustomizer

public McpClientBuilder httpRequestCustomizer(McpSyncHttpClientRequestCustomizer customizer)

设置该配置项。

Registers a per-request HTTP customizer for dynamic request modification (only applicable for HTTP transports: SSE and StreamableHTTP).

始于Since 2.0.0

参数Parameters

名称Name	类型Type	说明Description
`customizer`	McpSyncHttpClientRequestCustomizer	customizer（类型 `McpSyncHttpClientRequestCustomizer`）。per-request customizer invoked before each HTTP request

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:266–271

header

public McpClientBuilder header(String key, String value)

设置请求头。

Adds an HTTP header (only applicable for HTTP transports).

参数Parameters

名称Name	类型Type	说明Description
`key`	String	键（类型 `String`）。header name
`value`	String	值（类型 `String`）。header value

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:280–285

headers

public McpClientBuilder headers(Map<String, String> headers)

设置请求头。

Sets multiple HTTP headers (only applicable for HTTP transports).

参数Parameters

名称Name	类型Type	说明Description
`headers`	Map<String, String>	请求头（类型 `Map`）。map of header name-value pairs

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:293–298

queryParam

public McpClientBuilder queryParam(String key, String value)

设置查询参数。

Adds a query parameter to the URL (only applicable for HTTP transports).

参数Parameters

名称Name	类型Type	说明Description
`key`	String	键（类型 `String`）。query parameter name
`value`	String	值（类型 `String`）。query parameter value

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:312–317

queryParams

public McpClientBuilder queryParams(Map<String, String> queryParams)

设置查询参数。

Sets multiple query parameters (only applicable for HTTP transports).

参数Parameters

名称Name	类型Type	说明Description
`queryParams`	Map<String, String>	查询参数（类型 `Map`）。map of query parameter name-value pairs

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:329–334

timeout

public McpClientBuilder timeout(Duration timeout)

设置请求超时时长。

Sets the request timeout duration.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	Duration	超时时间（类型 `Duration`）。timeout duration

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:342–345

initializationTimeout

public McpClientBuilder initializationTimeout(Duration timeout)

设置该配置项。

Sets the initialization timeout duration.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	Duration	超时时间（类型 `Duration`）。timeout duration

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:353–356

protocolVersions

public McpClientBuilder protocolVersions(String... versions)

设置该配置项。

Sets the MCP protocol versions that the client supports.

参数Parameters

名称Name	类型Type	说明Description
`versions` varargs	String...	versions（类型 `String...`）。one or more protocol version strings (e.g., "2024-11-05", "2025-03-26")

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if no versions are provided

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:378–390

asyncElicitation

public McpClientBuilder asyncElicitation(Function<ElicitRequest, Mono<ElicitResult>> handler)

设置该配置项。

Registers an asynchronous elicitation handler for processing elicit requests from the server.

参数Parameters

名称Name	类型Type	说明Description
`handler`	Function<ElicitRequest, Mono<ElicitResult>>	处理器（类型 `Function >`）。function to handle elicit requests asynchronously

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:424–427

syncElicitation

public McpClientBuilder syncElicitation(Function<ElicitRequest, ElicitResult> handler)

设置该配置项。

Registers a synchronous elicitation handler for processing elicit requests from the server.

参数Parameters

名称Name	类型Type	说明Description
`handler`	Function<ElicitRequest, ElicitResult>	处理器（类型 `Function`）。function to handle elicit requests synchronously

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:460–463

propagateMeta

public McpClientBuilder propagateMeta(boolean propagateMeta)

设置该配置项。

Configures whether request metadata is propagated to this MCP server.

参数Parameters

名称Name	类型Type	说明Description
`propagateMeta`	boolean	propagate 元数据（类型 `boolean`）。true to propagate metadata (default), false to omit the `meta` field entirely from tool call requests

返回Returns McpClientBuilder

返回McpClientBuilder。this builder

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:487–490

buildAsync

public Mono<McpClientWrapper> buildAsync()

构建异步。

Builds an asynchronous MCP client wrapper.

返回Returns Mono<McpClientWrapper>

返回Mono。Mono emitting the async client wrapper

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:497–535

buildSync

public McpClientWrapper buildSync()

构建同步。

Builds a synchronous MCP client wrapper (blocking operations).

返回Returns McpClientWrapper

返回McpClientWrapper。synchronous client wrapper

源码Source io/agentscope/core/tool/mcp/McpClientBuilder.java:542–576