Interface ToolHandler

All Known Subinterfaces:

ToolHandler.Cancellable

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface ToolHandler

The body of an MCP tool: takes the parsed argument JSON and the shared ServerContext, returns the structured result payload.

Contract:

• arguments is never null - a call with no arguments arrives as an empty object node;
• the returned ObjectNode becomes the tool result's structuredContent (and, serialized, its text content);
• throwing any exception is safe: the server converts it into an MCP tool error result (isError: true with the exception message) rather than a protocol failure, so validation can simply throw new IllegalArgumentException("field 'x' is required");
• text that comes from a remote system (an Equinix API field, a PeeringDB name, a pricing error) is put into the payload through UntrustedText, so the server can sanitise it and label it as data.

Cancellation

The server always invokes handle(JsonNode, ServerContext, CancellationSignal). Its default checks the signal once and then runs handle(JsonNode, ServerContext), which suits a read-only tool: a call the client already cancelled does not start. A handler that must observe cancellation while it runs (for example before sending an irreversible request) implements ToolHandler.Cancellable.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ToolHandler.Cancellable	A handler that observes its cancellation signal while it runs.

Method Summary

Modifier and Type	Method	Description
com.fasterxml.jackson.databind.node.ObjectNode	handle(com.fasterxml.jackson.databind.JsonNode arguments, ServerContext context)	Executes the tool.
default com.fasterxml.jackson.databind.node.ObjectNode	handle(com.fasterxml.jackson.databind.JsonNode arguments, ServerContext context, CancellationSignal cancellation)	Executes the tool under a cancellation signal.

Method Details

handle

com.fasterxml.jackson.databind.node.ObjectNode handle(com.fasterxml.jackson.databind.JsonNode arguments,
 ServerContext context)
                                               throws Exception

Executes the tool.

Parameters:

arguments - the parsed tool-call arguments (an object node, never null)

context - the shared server context of lazily-built SDK facades

Returns:

the structured result payload

Throws:

Exception - on any failure - surfaced to the caller as a tool error result

handle

default com.fasterxml.jackson.databind.node.ObjectNode handle(com.fasterxml.jackson.databind.JsonNode arguments,
 ServerContext context,
 CancellationSignal cancellation)
                                                       throws Exception

Executes the tool under a cancellation signal. The default refuses to start a call that is already cancelled and otherwise delegates to handle(JsonNode, ServerContext).

Parameters:

arguments - the parsed tool-call arguments (an object node, never null)

context - the shared server context

cancellation - the call's cancellation signal; never null

Returns:

the structured result payload

Throws:

Exception - on any failure - surfaced to the caller as a tool error result