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.

Each method exists in two forms: a current one, and a deprecated one that uses Jackson's JsonNode. The bridge between them runs one way only: the current method delegates to the deprecated one, so a transport written against the old API keeps working, but the deprecated one throws rather than delegating back. Two mutually-delegating defaults would recurse if an implementation overrode neither, and this way that mistake fails immediately instead.

New implementations should override the current forms - sendInitializeRequest, sendRequest and sendMessage - which are the ones the client calls. A transport migrating from the deprecated forms has to move its own internal calls at the same time: those keep compiling and then throw at runtime, often somewhere the exception is swallowed. Building with -Xlint:removal -Werror finds them mechanically.

  • 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.

    • initialize

      @Deprecated(since="1.20.0", forRemoval=true) default CompletableFuture<com.fasterxml.jackson.databind.JsonNode> initialize(McpInitializeRequest request)
      Deprecated, for removal: This API element is subject to removal in a future version.
      implement sendInitializeRequest(McpInitializeRequest) instead, which does not expose Jackson types. This default throws; it does not delegate, because two mutually-delegating defaults would recurse.
      Sends the "initialize" message to the MCP server to negotiate capabilities, supported protocol version etc. When this method returns successfully, the transport is fully initialized and ready to be used. This has to be called AFTER the "start" method. Only used with the legacy MCP protocol (versions up to 2025-11-25). Modern protocol uses server/discover instead.

    • sendInitializeRequest

      default 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. Only used with the legacy MCP protocol (versions up to 2025-11-25); the modern protocol uses server/discover.

    • executeOperationWithResponse

      @Deprecated(since="1.20.0", forRemoval=true) default CompletableFuture<com.fasterxml.jackson.databind.JsonNode> executeOperationWithResponse(McpClientMessage request)
      Deprecated, for removal: This API element is subject to removal in a future version.
      implement sendRequest(McpClientMessage) instead, which does not expose Jackson types. This default throws; it does not delegate, because two mutually-delegating defaults would recurse.
      Executes an operation that expects a response from the server.

    • sendRequest

      default CompletableFuture<String> sendRequest(McpClientMessage request)
      Sends a JSON-RPC request and returns the server's response as unparsed JSON text.

    • executeOperationWithResponse

      @Deprecated(since="1.20.0", forRemoval=true) default CompletableFuture<com.fasterxml.jackson.databind.JsonNode> executeOperationWithResponse(McpCallContext context)
      Deprecated, for removal: This API element is subject to removal in a future version.
      implement sendRequest(McpCallContext) instead, which does not expose Jackson types. This default throws; it does not delegate, because two mutually-delegating defaults would recurse.
      Executes an operation that expects a response from the server.

    • sendRequest

      default CompletableFuture<String> sendRequest(McpCallContext context)
      Sends a JSON-RPC request and returns the server's response as unparsed JSON text.

    • executeOperationWithoutResponse

      @Deprecated(since="1.20.0", forRemoval=true) default void executeOperationWithoutResponse(McpClientMessage request)
      Deprecated, for removal: This API element is subject to removal in a future version.
      implement sendMessage(McpClientMessage) instead, which is named for what MCP calls it. This default throws; it does not delegate, because two mutually-delegating defaults would recurse.
      Sends a message that does not expect a reply.

    • sendMessage

      default void sendMessage(McpClientMessage request)
      Sends a message that does not expect a reply - in MCP terms a notification, or a response to a server-initiated request.

    • executeOperationWithoutResponse

      @Deprecated(since="1.20.0", forRemoval=true) default void executeOperationWithoutResponse(McpCallContext context)
      Deprecated, for removal: This API element is subject to removal in a future version.
      implement sendMessage(McpCallContext) instead, which is named for what MCP calls it. This default throws; it does not delegate, because two mutually-delegating defaults would recurse.
      Sends a message that does not expect a reply.

    • sendMessage

      default 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.

    • 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.