Package org.apache.juneau.rest.client.mcp.v20260728

Class McpClient

java.lang.Object

org.apache.juneau.rest.client.mcp.AbstractMcpClient

org.apache.juneau.rest.client.mcp.v20260728.McpClient

All Implemented Interfaces:

Closeable, AutoCloseable

public final class McpClient
extends AbstractMcpClient

Typed 2026-07-28 Model Context Protocol (MCP) client facade.

Extends AbstractMcpClient, adding one typed method per 2026-07-28 JSON-RPC method (see McpMethods). Every method stamps the SEP-2243 params._meta envelope (protocol version, client capabilities, client info, and any supplied trace-context fields), builds the corresponding v2 request bean, wraps it in a JsonRpcRequest with the required Mcp-Method/Mcp-Name headers, delegates to the inherited AbstractMcpClient.send(JsonRpcRequest, Map), and then either returns the result re-marshaled into its typed v2 result bean, or throws an McpException built from the response's error.

An optional McpResponseCache can be supplied via McpClient.Builder.responseCache(McpResponseCache) to serve repeat identical calls from cache instead of the wire, keyed off the method and business params (never the per-call _meta, so a per-request trace-context supplier does not defeat the cache).

A server-initiated request delivered over the duplex event-stream channel is routed through the McpDuplexDispatcher registered via setServerRequestHandler(McpServerRequestHandler).

Since:

10.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	McpClient.Builder	Fluent builder for McpClient.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_MAX_ELICITATION_ROUNDS	Default maximum number of input_required resume rounds the *WithElicitation helpers will drive before throwing McpElicitationLimitException.

Method Summary

Modifier and Type	Method	Description
static McpClient.Builder	builder()	Creates a new builder.
Map<String,Object>	callRaw(String method, RequestParams<?> params)	Performs a JSON-RPC call using a caller-supplied, fully-populated request bean, returning the raw result payload without deserializing into a specific Result subtype.
CallToolResult	callTool(String name, Map<String,Object> arguments)	Sends "tools/call".
String	callToolText(String name, Map<String,Object> arguments)	Convenience for callTool(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) followed by CallToolResult.firstText().
CallToolResult	callToolWithElicitation(String name, Map<String,Object> arguments, McpElicitationHandler handler)	Invokes "tools/call", transparently answering any MCP 2026-07-28 SEP-2322 input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.
CallToolResult	callToolWithElicitation(String name, Map<String,Object> arguments, McpElicitationHandler handler, int maxRounds)	Invokes "tools/call", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.
CompleteResult	complete(CompletionReference ref, String argumentName, String argumentValue, Map<String,String> contextArguments)	Sends "completion/complete".
static McpClient	connect(String endpoint)	Builds a client for endpoint with default settings and performs its one mandatory handshake call, returning a ready-to-use client.
static McpClient	connect(McpClient.Builder builder)	Builds a client from a caller-configured builder and performs its one mandatory handshake call, returning a ready-to-use client.
ServerDiscoverResult	discoveredServer()	Returns the ServerDiscoverResult cached from the most recent serverDiscover() call.
GetPromptResult	getPrompt(String name, Map<String,Object> arguments)	Sends "prompts/get".
GetPromptResult	getPromptWithElicitation(String name, Map<String,Object> arguments, McpElicitationHandler handler)	Invokes "prompts/get", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.
GetPromptResult	getPromptWithElicitation(String name, Map<String,Object> arguments, McpElicitationHandler handler, int maxRounds)	Invokes "prompts/get", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.
McpSubscriptionHandle	listen(SubscriptionFilter filter, McpSubscriptionListener listener)	Sends "subscriptions/listen", opening a managed, held-open notification stream on a background thread and dispatching decoded frames to listener until the returned handle is closed, the server completes gracefully, or the connection drops.
ListPromptsResult	listPrompts()	Sends "prompts/list".
ListResourcesResult	listResources()	Sends "resources/list".
ListResourceTemplatesResult	listResourceTemplates()	Sends "resources/templates/list".
ListToolsResult	listTools()	Sends "tools/list".
PingResult	ping()	Sends "ping" to verify server liveness.
ReadResourceResult	readResource(String uri)	Sends "resources/read".
ReadResourceResult	readResourceWithElicitation(String uri, McpElicitationHandler handler)	Invokes "resources/read", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.
ReadResourceResult	readResourceWithElicitation(String uri, McpElicitationHandler handler, int maxRounds)	Invokes "resources/read", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.
ServerDiscoverResult	serverDiscover()	Sends "server/discover".
McpClient	setServerRequestHandler(McpServerRequestHandler value)	Registers the handler invoked for server-initiated requests delivered over the duplex event-stream channel (see McpDuplexDispatcher).

Methods inherited from class org.apache.juneau.rest.client.mcp.AbstractMcpClient

close, openEventStream, openEventStream, openEventStream, send, send

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_MAX_ELICITATION_ROUNDS

public static final int DEFAULT_MAX_ELICITATION_ROUNDS

Default maximum number of input_required resume rounds the *WithElicitation helpers will drive before throwing McpElicitationLimitException.

See Also:

• Constant Field Values

Method Details

builder

public static McpClient.Builder builder()

Creates a new builder.

Returns:

A new builder. Never null.

connect

public static McpClient connect(String endpoint)
                         throws IOException

Builds a client for endpoint with default settings and performs its one mandatory handshake call, returning a ready-to-use client.

2026-07-28 has no initialize method - serverDiscover() is this revision's handshake - so unlike v20250618's McpClient, forgetting it is a real footgun: nothing in this class's type system forces a caller to call it before callTool(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>), listTools(), etc. This is the sanctioned one-expression path for the common case of connecting with default settings; use connect(Builder) to customize the transport, interceptors, or other builder settings first.

Parameters:

endpoint - The absolute endpoint URL (e.g. "http://localhost:8080/mcp"). Must not be null.

Returns:

A new client that has already completed serverDiscover() exactly once. Never null.

Throws:

IOException - If a transport-level or (de)serialization error occurs opening the connection.

McpException - If the server returned a JSON-RPC error for "server/discover".

connect

public static McpClient connect(McpClient.Builder builder)
                         throws IOException

Builds a client from a caller-configured builder and performs its one mandatory handshake call, returning a ready-to-use client.

If serverDiscover() fails, the just-built client is closed before the exception propagates - a caller that only ever sees an exception from connect(...) never ends up owning a client (and its underlying transport resources) it has no reference to.

Parameters:

builder - The configured builder to build from. Must not be null.

Returns:

A new client that has already completed serverDiscover() exactly once. Never null.

Throws:

IOException - If a transport-level or (de)serialization error occurs opening the connection.

McpException - If the server returned a JSON-RPC error for "server/discover".

serverDiscover

public ServerDiscoverResult serverDiscover()
                                    throws IOException

Sends "server/discover".

Caches its result, so a subsequent discoveredServer() call (including one following the mandatory discovery connect(Builder) already performs) does not need a repeat round trip.

Returns:

The server-discover result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

discoveredServer

public ServerDiscoverResult discoveredServer()

Returns the ServerDiscoverResult cached from the most recent serverDiscover() call.

A client built via connect(String)/connect(Builder) already has this populated from the mandatory handshake call, so a caller that only needs the discovery info (server capabilities, supported versions, etc.) does not need to invoke serverDiscover() again just to read it.

Returns:

The most recently discovered server info, or null if serverDiscover() has not been called on this client, or the most recent call returned a null result.

ping

public PingResult ping()
                throws IOException

Sends "ping" to verify server liveness.

Returns:

The ping result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

listTools

public ListToolsResult listTools()
                          throws IOException

Sends "tools/list".

Returns:

The tools-list result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

callTool

public CallToolResult callTool(String name,
 Map<String,Object> arguments)
                        throws IOException

Sends "tools/call".

Parameters:

name - The tool name to invoke.

arguments - The tool arguments. Can be null (sent as an empty object).

Returns:

The call-tool result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

callToolText

public String callToolText(String name,
 Map<String,Object> arguments)
                    throws IOException

Convenience for callTool(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) followed by CallToolResult.firstText().

Kills the ((TextContent)result.getContent().get(i)).getText() cast-and-scan that a caller who only wants the tool's text result would otherwise repeat at every call site.

Parameters:

name - The tool name to invoke.

arguments - The tool arguments. Can be null (sent as an empty object).

Returns:

The first TextContent block's text found while scanning the result's content list in order, or null if the content list is empty or unset, it contains no TextContent block, or callTool(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) itself returned a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

listPrompts

public ListPromptsResult listPrompts()
                              throws IOException

Sends "prompts/list".

Returns:

The prompts-list result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

getPrompt

public GetPromptResult getPrompt(String name,
 Map<String,Object> arguments)
                          throws IOException

Sends "prompts/get".

Parameters:

name - The prompt name to fetch.

arguments - The prompt argument values. Can be null (sent as an empty object).

Returns:

The get-prompt result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

listResources

public ListResourcesResult listResources()
                                  throws IOException

Sends "resources/list".

Returns:

The resources-list result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

readResource

public ReadResourceResult readResource(String uri)
                                throws IOException

Sends "resources/read".

Parameters:

uri - The resource URI to read.

Returns:

The read-resource result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

listResourceTemplates

public ListResourceTemplatesResult listResourceTemplates()
                                                  throws IOException

Sends "resources/templates/list".

Returns:

The resource-templates-list result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

complete

public CompleteResult complete(CompletionReference ref,
 String argumentName,
 String argumentValue,
 Map<String,String> contextArguments)
                        throws IOException

Sends "completion/complete".

Parameters:

ref - The completion target (a declared prompt or resource template reference).

argumentName - The prompt argument or resource-template variable being completed.

argumentValue - The current partial value of argumentName.

contextArguments - Previously-resolved argument values for context, or null to omit the context object entirely.

Returns:

The completion result. Never null on success unless the server returns a null result.

Throws:

IOException - If a transport-level or (de)serialization error occurs.

McpException - If the server returned a JSON-RPC error.

callRaw

public Map<String,Object> callRaw(String method,
 RequestParams<?> params)
                           throws IOException

Performs a JSON-RPC call using a caller-supplied, fully-populated request bean, returning the raw result payload without deserializing into a specific Result subtype.

Every convenience method on this class (callTool(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>), getPrompt(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>), readResource(java.lang.String), etc.) both builds its own request bean internally and deserializes strictly into one known result type, so none of them can represent a paused input_required response (MCP 2026-07-28 SEP-2322 Multi-Round-Trip Requests) or carry the requestState/inputResponses fields a resume call needs to set. This method exists specifically for MRTR-aware callers that must both populate those fields on the request (e.g. on a CallToolRequest) and branch on the response's resultType themselves, decoding into a typed result only once resultType reads "complete".

Parameters:

method - The JSON-RPC method (e.g. McpMethods.TOOLS_CALL).

params - The fully-populated request bean.

Returns:

The raw result as a generic Map, exactly as received over the wire, before any subclass-specific deserialization. Never null on a successful JSON-RPC response.

Throws:

IOException - On a transport failure.

McpException - If the server returns a JSON-RPC error.

callToolWithElicitation

public CallToolResult callToolWithElicitation(String name,
 Map<String,Object> arguments,
 McpElicitationHandler handler)
                                       throws IOException

Invokes "tools/call", transparently answering any MCP 2026-07-28 SEP-2322 input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.

This is the ergonomic counterpart to hand-driving the resume loop with callRaw(java.lang.String, org.apache.juneau.bean.mcp.v20260728.RequestParams<?>), ElicitationRequests, and ElicitationResponses: it detects each pause, decodes that round's requests, calls handler for the answers, echoes them back with the carried requestState, and repeats until the server returns a non-input_required result, which is decoded into a typed CallToolResult. callRaw(java.lang.String, org.apache.juneau.bean.mcp.v20260728.RequestParams<?>) remains available as the low-level escape hatch.

Parameters:

name - The tool name to invoke.

arguments - The tool arguments. Can be null (sent as an empty object).

handler - The elicitation answer callback, invoked once per pause. Must not be null.

Returns:

The terminal call-tool result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past DEFAULT_MAX_ELICITATION_ROUNDS.

callToolWithElicitation

public CallToolResult callToolWithElicitation(String name,
 Map<String,Object> arguments,
 McpElicitationHandler handler,
 int maxRounds)
                                       throws IOException

Invokes "tools/call", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.

Parameters:

name - The tool name to invoke.

arguments - The tool arguments. Can be null (sent as an empty object).

handler - The elicitation answer callback, invoked once per pause. Must not be null.

maxRounds - The maximum number of resume rounds before McpElicitationLimitException is thrown. Must be ≥ 1.

Returns:

The terminal call-tool result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, maxRounds is not ≥ 1, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past maxRounds.

getPromptWithElicitation

public GetPromptResult getPromptWithElicitation(String name,
 Map<String,Object> arguments,
 McpElicitationHandler handler)
                                         throws IOException

Invokes "prompts/get", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.

Parameters:

name - The prompt name to fetch.

arguments - The prompt argument values. Can be null (sent as an empty object).

handler - The elicitation answer callback, invoked once per pause. Must not be null.

Returns:

The terminal get-prompt result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past DEFAULT_MAX_ELICITATION_ROUNDS.

getPromptWithElicitation

public GetPromptResult getPromptWithElicitation(String name,
 Map<String,Object> arguments,
 McpElicitationHandler handler,
 int maxRounds)
                                         throws IOException

Invokes "prompts/get", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.

Parameters:

name - The prompt name to fetch.

arguments - The prompt argument values. Can be null (sent as an empty object).

handler - The elicitation answer callback, invoked once per pause. Must not be null.

maxRounds - The maximum number of resume rounds before McpElicitationLimitException is thrown. Must be ≥ 1.

Returns:

The terminal get-prompt result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, maxRounds is not ≥ 1, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past maxRounds.

readResourceWithElicitation

public ReadResourceResult readResourceWithElicitation(String uri,
 McpElicitationHandler handler)
                                               throws IOException

Invokes "resources/read", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, using the default max-rounds bound.

Parameters:

uri - The resource URI to read.

handler - The elicitation answer callback, invoked once per pause. Must not be null.

Returns:

The terminal read-resource result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past DEFAULT_MAX_ELICITATION_ROUNDS.

readResourceWithElicitation

public ReadResourceResult readResourceWithElicitation(String uri,
 McpElicitationHandler handler,
 int maxRounds)
                                               throws IOException

Invokes "resources/read", transparently answering any input_required elicitation pauses via handler until a terminal result is reached, bounded by maxRounds.

Parameters:

uri - The resource URI to read.

handler - The elicitation answer callback, invoked once per pause. Must not be null.

maxRounds - The maximum number of resume rounds before McpElicitationLimitException is thrown. Must be ≥ 1.

Returns:

The terminal read-resource result. Never null on success unless the server returns a null result.

Throws:

IllegalArgumentException - If handler is null, maxRounds is not ≥ 1, or handler returns a null result or a result map containing a null value for a requested id.

IOException - If a transport-level or (de)serialization error occurs, or handler throws it.

McpException - If the server returned a JSON-RPC error.

McpElicitationLimitException - If the server keeps pausing past maxRounds.

listen

public McpSubscriptionHandle listen(SubscriptionFilter filter,
 McpSubscriptionListener listener)
                             throws IOException

Sends "subscriptions/listen", opening a managed, held-open notification stream on a background thread and dispatching decoded frames to listener until the returned handle is closed, the server completes gracefully, or the connection drops.

Only the initial "subscriptions/listen" POST (opening the stream) is synchronous — a transport-level failure at that point surfaces here as a thrown IOException. Every frame after that (the mandatory acknowledged frame, zero or more change notifications, and the eventual terminal frame) is decoded on a dedicated background thread and delivered to listener; frame-processing failures surface via McpSubscriptionListener.onError(Throwable), never as a thrown exception from this method. This does not reuse pumpNextServerMessage() (single-shot, closes its stream after at most one event) or McpDuplexDispatcher (request/response-shaped, single registration) — listen(...) needs its own long-lived, multi-frame decode loop.

Parameters:

filter - The subscription filter (toolsListChanged/promptsListChanged/resourcesListChanged/resourceSubscriptions). Must not be null.

listener - The typed callback sink. Must not be null.

Returns:

A handle to cancel/close the subscription. Never null.

Throws:

IOException - If the initial listen request/stream-open fails.

setServerRequestHandler

public McpClient setServerRequestHandler(McpServerRequestHandler value)

Registers the handler invoked for server-initiated requests delivered over the duplex event-stream channel (see McpDuplexDispatcher).

Parameters:

value - The handler to register. Passing null de-registers any previously-registered handler.

Returns:

This object.