Package io.modelcontextprotocol.server.transport

Class WebFluxSseServerTransport

java.lang.Object
io.modelcontextprotocol.server.transport.WebFluxSseServerTransport
All Implemented Interfaces:
McpTransport, ServerMcpTransport
public class WebFluxSseServerTransport extends Object implements ServerMcpTransport
Server-side implementation of the MCP (Model Context Protocol) HTTP transport using Server-Sent Events (SSE). This implementation provides a bidirectional communication channel between MCP clients and servers using HTTP POST for client-to-server messages and SSE for server-to-client messages.

Key features:

  • Implements the ServerMcpTransport interface for MCP server transport functionality
  • Uses WebFlux for non-blocking request handling and SSE support
  • Maintains client sessions for reliable message delivery
  • Supports graceful shutdown with session cleanup
  • Thread-safe message broadcasting to multiple clients

The transport sets up two main endpoints:

  • SSE endpoint (/sse) - For establishing SSE connections with clients
  • Message endpoint (configurable) - For receiving JSON-RPC messages from clients

This implementation is thread-safe and can handle multiple concurrent client connections. It uses ConcurrentHashMap for session management and Reactor's Sinks for thread-safe message broadcasting.

Author:
Christian Tzolov, Alexandros Pappas
See Also:

  • Field Details

    • MESSAGE_EVENT_TYPE

      public static final String MESSAGE_EVENT_TYPE
      Event type for JSON-RPC messages sent through the SSE connection.
      See Also:

    • ENDPOINT_EVENT_TYPE

      public static final String ENDPOINT_EVENT_TYPE
      Event type for sending the message endpoint URI to clients.
      See Also:

    • DEFAULT_SSE_ENDPOINT

      public static final String DEFAULT_SSE_ENDPOINT
      Default SSE endpoint path as specified by the MCP transport specification.
      See Also:

  • Constructor Details

    • WebFluxSseServerTransport

      public WebFluxSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)
      Constructs a new WebFlux SSE server transport instance.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of MCP messages. Must not be null.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages. This endpoint will be communicated to clients during SSE connection setup. Must not be null.
      Throws:
      IllegalArgumentException - if either parameter is null

    • WebFluxSseServerTransport

      public WebFluxSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)
      Constructs a new WebFlux SSE server transport instance with the default SSE endpoint.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of MCP messages. Must not be null.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages. This endpoint will be communicated to clients during SSE connection setup. Must not be null.
      Throws:
      IllegalArgumentException - if either parameter is null

  • Method Details

    • connect

      public reactor.core.publisher.Mono<Void> connect(Function<reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>,reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>> handler)
      Configures the message handler for this transport. In the WebFlux SSE implementation, this method stores the handler for processing incoming messages but doesn't establish any connections since the server accepts connections rather than initiating them.
      Specified by:
      connect in interface McpTransport
      Parameters:
      handler - A function that processes incoming JSON-RPC messages and returns responses. This handler will be called for each message received through the message endpoint.
      Returns:
      An empty Mono since the server doesn't initiate connections

    • sendMessage

      public reactor.core.publisher.Mono<Void> sendMessage(McpSchema.JSONRPCMessage message)
      Broadcasts a JSON-RPC message to all connected clients through their SSE connections. The message is serialized to JSON and sent as a server-sent event to each active session.

      The method:

      • Serializes the message to JSON
      • Creates a server-sent event with the message data
      • Attempts to send the event to all active sessions
      • Tracks and reports any delivery failures
      Specified by:
      sendMessage in interface McpTransport
      Parameters:
      message - The JSON-RPC message to broadcast
      Returns:
      A Mono that completes when the message has been sent to all sessions, or errors if any session fails to receive the message

    • unmarshalFrom

      public <T> T unmarshalFrom(Object data, com.fasterxml.jackson.core.type.TypeReference<T> typeRef)
      Converts data from one type to another using the configured ObjectMapper. This method is primarily used for converting between different representations of JSON-RPC message data.
      Specified by:
      unmarshalFrom in interface McpTransport
      Type Parameters:
      T - The target type to convert to
      Parameters:
      data - The source data to convert
      typeRef - Type reference describing the target type
      Returns:
      The converted data
      Throws:
      IllegalArgumentException - if the conversion fails

    • closeGracefully

      public reactor.core.publisher.Mono<Void> closeGracefully()
      Initiates a graceful shutdown of the transport. This method ensures all active sessions are properly closed and cleaned up.

      The shutdown process:

      • Marks the transport as closing to prevent new connections
      • Closes each active session
      • Removes closed sessions from the sessions map
      • Times out after 5 seconds if shutdown takes too long
      Specified by:
      closeGracefully in interface McpTransport
      Returns:
      A Mono that completes when all sessions have been closed

    • getRouterFunction

      public org.springframework.web.reactive.function.server.RouterFunction<?> getRouterFunction()
      Returns the WebFlux router function that defines the transport's HTTP endpoints. This router function should be integrated into the application's web configuration.

      The router function defines two endpoints:

      • GET {sseEndpoint} - For establishing SSE connections
      • POST {messageEndpoint} - For receiving client messages
      Returns:
      The configured RouterFunction for handling HTTP requests