Interface McpTransport

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
DockerMcpTransport, StdioMcpTransport, StreamableHttpMcpTransport, WebSocketMcpTransport
public interface McpTransport extends Closeable
The transport contract between the MCP client and a server connection.

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.

  • Method Details

    • start

      void start(McpOperationHandler messageHandler)
      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.

    • sendInitializeRequest

      CompletableFuture<String> sendInitializeRequest(McpInitializeRequest request)
      Sends the MCP InitializeRequest and 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 uses server/discover.

    • sendRequest

      CompletableFuture<String> sendRequest(McpCallContext context)
      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

      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.

    • sendMessage

      void sendMessage(McpCallContext context)
      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

      default void sendMessage(McpClientMessage request)
      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

      void onFailure(Runnable actionOnFailure)

    • 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

      default void setProtocolVersion(String protocolVersion)
      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 explicit notifications/cancelled message to cancel an in-progress request. Transports that use per-request SSE streams (like Streamable HTTP) cancel by closing the stream and should return false. Transports that share a single channel (like stdio) must return true so the server knows which request to cancel.

      Note: when using the legacy protocol (2025-11-25), the client always sends notifications/cancelled regardless 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.