Interface McpTransport
- All Superinterfaces:
AutoCloseable, Closeable
- All Known Implementing Classes:
DockerMcpTransport, StdioMcpTransport, StreamableHttpMcpTransport, WebSocketMcpTransport
Responses cross this interface as unparsed JSON text, so that a transport does not need a JSON
library. A transport registers each request it sends with
McpOperationHandler.expectResponse(Long, CompletableFuture) and passes every message it
receives to McpOperationHandler.onMessage(String).
Besides the lifecycle methods, a transport implements three methods:
sendInitializeRequest(McpInitializeRequest), sendRequest(McpCallContext) and
sendMessage(McpCallContext). The overloads that take a bare McpClientMessage
wrap it in a McpCallContext without per-call headers or _meta.
stop() undoes what start(McpOperationHandler) did, so that the transport can
be started again, while Closeable.close() releases the transport for good. A client whose
initialization fails stops its transport, which the caller keeps owning. Both must also work when
start failed or was never called, and may be called more than once.
-
Method Summary
Modifier and TypeMethodDescriptionvoidPerforms transport-specific health checks, if applicable.voiddefault booleanReturns whether this transport requires an explicitnotifications/cancelledmessage to cancel an in-progress request.Sends the MCPInitializeRequestand returns the server's response as unparsed JSON text, so that a transport does not need a JSON library.voidsendMessage(McpCallContext context) Sends a message that does not expect a reply - in MCP terms a notification, or a response to a server-initiated request.default voidsendMessage(McpClientMessage request) Sends a message that does not expect a reply and carries no per-call headers or_meta.sendRequest(McpCallContext context) Sends a JSON-RPC request and returns the server's response as unparsed JSON text.default CompletableFuture<String> sendRequest(McpClientMessage request) Sends a JSON-RPC request that carries no per-call headers or_meta, and returns the server's response as unparsed JSON text.default voidsetModernProtocol(boolean modernProtocol) Informs the transport whether the modern MCP protocol (2026-07-28 or later) is in use.default voidsetProtocolVersion(String protocolVersion) Sets the protocol version string to be sent in the MCP-Protocol-Version HTTP header.voidstart(McpOperationHandler messageHandler) Creates a connection to the MCP server (runs the server as a subprocess if needed).default voidstop()Releases whatstart(McpOperationHandler)acquired, such as a subprocess, a container or a connection, without closing the transport itself, so that it can be started again: for a transport that connects per request it amounts to forgetting the session, the equivalent of a reconnection.
-
Method Details
-
start
Creates a connection to the MCP server (runs the server as a subprocess if needed). This does NOT yet send the "initialize" message to negotiate capabilities. -
stop
default void stop()Releases whatstart(McpOperationHandler)acquired, such as a subprocess, a container or a connection, without closing the transport itself, so that it can be started again: for a transport that connects per request it amounts to forgetting the session, the equivalent of a reconnection. The client calls it when its construction fails, because the caller keeps owning the transport in that case. The default does nothing, which leaks whateverstartacquired until the nextstartorclose: a transport that acquires anything there should override it.- Since:
- 1.24.0
-
sendInitializeRequest
Sends the MCPInitializeRequestand returns the server's response as unparsed JSON text, so that a transport does not need a JSON library. This has to be called AFTER the "start" method; when it returns successfully, the transport is ready to be used. Only used with the legacy MCP protocol (versions up to 2025-11-25); the modern protocol usesserver/discover. -
sendRequest
Sends a JSON-RPC request and returns the server's response as unparsed JSON text. The context carries the message and its per-call headers and_meta, which the transport applies. -
sendRequest
Sends a JSON-RPC request that carries no per-call headers or_meta, and returns the server's response as unparsed JSON text. -
sendMessage
Sends a message that does not expect a reply - in MCP terms a notification, or a response to a server-initiated request. The context carries the message and its per-call headers and_meta, which the transport applies. -
sendMessage
Sends a message that does not expect a reply and carries no per-call headers or_meta. -
checkHealth
void checkHealth()Performs transport-specific health checks, if applicable. This is called by `McpClient.checkHealth()` as the first check before performing a check by sending a 'ping' over the MCP protocol. The purpose is that the transport may have some specific and faster ways to detect that it is broken, like for example, the STDIO transport can fail the check if it detects that the server subprocess isn't alive anymore. -
onFailure
-
setModernProtocol
default void setModernProtocol(boolean modernProtocol) Informs the transport whether the modern MCP protocol (2026-07-28 or later) is in use. HTTP-based transports use this to switch between modern headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name) and legacy session management (Mcp-Session-Id). Default implementation is a no-op (for transports like stdio/WebSocket that don't need it). -
setProtocolVersion
Sets the protocol version string to be sent in the MCP-Protocol-Version HTTP header. Only relevant for HTTP-based transports in modern protocol mode. Default implementation is a no-op. -
requiresCancellationNotification
default boolean requiresCancellationNotification()Returns whether this transport requires an explicitnotifications/cancelledmessage to cancel an in-progress request. Transports that use per-request SSE streams (like Streamable HTTP) cancel by closing the stream and should returnfalse. Transports that share a single channel (like stdio) must returntrueso the server knows which request to cancel.Note: when using the legacy protocol (2025-11-25), the client always sends
notifications/cancelledregardless of this value, because the legacy spec states that disconnection should not be interpreted as cancellation.Defaults to
true, which is the safe answer for a transport that shares a single channel; per-request-stream transports override it.
-