Package io.modelcontextprotocol.server.transport

Class WebMvcSseServerTransportProvider

java.lang.Object
io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider
All Implemented Interfaces:
McpServerTransportProvider, McpServerTransportProviderBase
public class WebMvcSseServerTransportProvider extends Object implements McpServerTransportProvider
Server-side implementation of the Model Context Protocol (MCP) transport layer using HTTP with Server-Sent Events (SSE) through Spring WebMVC. This implementation provides a bridge between synchronous WebMVC operations and reactive programming patterns to maintain compatibility with the reactive transport interface.

Key features:

  • Implements bidirectional communication using HTTP POST for client-to-server messages and SSE for server-to-client messages
  • Manages client sessions with unique IDs for reliable message delivery
  • Supports graceful shutdown with proper session cleanup
  • Provides JSON-RPC message handling through configured endpoints
  • Includes built-in error handling and logging

The transport operates on two main endpoints:

  • /sse - The SSE endpoint where clients establish their event stream connection
  • A configurable message endpoint where clients send their JSON-RPC messages via HTTP POST

This implementation uses ConcurrentHashMap to safely manage multiple client sessions in a thread-safe manner. Each client session is assigned a unique ID and maintains its own SSE connection.

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

    • WebMvcSseServerTransportProvider

      @Deprecated public WebMvcSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)
      Deprecated.
      Use the builder builder() instead for better configuration options.
      Constructs a new WebMvcSseServerTransportProvider instance with the default SSE endpoint.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of messages.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages via HTTP POST. This endpoint will be communicated to clients through the SSE connection's initial endpoint event.
      Throws:
      IllegalArgumentException - if either objectMapper or messageEndpoint is null

    • WebMvcSseServerTransportProvider

      @Deprecated public WebMvcSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)
      Deprecated.
      Use the builder builder() instead for better configuration options.
      Constructs a new WebMvcSseServerTransportProvider instance.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of messages.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages via HTTP POST. This endpoint will be communicated to clients through the SSE connection's initial endpoint event.
      sseEndpoint - The endpoint URI where clients establish their SSE connections.
      Throws:
      IllegalArgumentException - if any parameter is null

    • WebMvcSseServerTransportProvider

      @Deprecated public WebMvcSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String baseUrl, String messageEndpoint, String sseEndpoint)
      Deprecated.
      Use the builder builder() instead for better configuration options.
      Constructs a new WebMvcSseServerTransportProvider instance.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of messages.
      baseUrl - The base URL for the message endpoint, used to construct the full endpoint URL for clients.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages via HTTP POST. This endpoint will be communicated to clients through the SSE connection's initial endpoint event.
      sseEndpoint - The endpoint URI where clients establish their SSE connections.
      Throws:
      IllegalArgumentException - if any parameter is null

    • WebMvcSseServerTransportProvider

      @Deprecated public WebMvcSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String baseUrl, String messageEndpoint, String sseEndpoint, Duration keepAliveInterval)
      Deprecated.
      Use the builder builder() instead for better configuration options.
      Constructs a new WebMvcSseServerTransportProvider instance.
      Parameters:
      objectMapper - The ObjectMapper to use for JSON serialization/deserialization of messages.
      baseUrl - The base URL for the message endpoint, used to construct the full endpoint URL for clients.
      messageEndpoint - The endpoint URI where clients should send their JSON-RPC messages via HTTP POST. This endpoint will be communicated to clients through the SSE connection's initial endpoint event.
      sseEndpoint - The endpoint URI where clients establish their SSE connections. * @param keepAliveInterval The interval for sending keep-alive messages to
      Throws:
      IllegalArgumentException - if any parameter is null

  • Method Details

    • protocolVersion

      public String protocolVersion()
      Specified by:
      protocolVersion in interface McpServerTransportProviderBase

    • setSessionFactory

      public void setSessionFactory(McpServerSession.Factory sessionFactory)
      Specified by:
      setSessionFactory in interface McpServerTransportProvider

    • notifyClients

      public reactor.core.publisher.Mono<Void> notifyClients(String method, Object params)
      Broadcasts a notification to all connected clients through their SSE connections. The message is serialized to JSON and sent as an SSE event with type "message". If any errors occur during sending to a particular client, they are logged but don't prevent sending to other clients.
      Specified by:
      notifyClients in interface McpServerTransportProviderBase
      Parameters:
      method - The method name for the notification
      params - The parameters for the notification
      Returns:
      A Mono that completes when the broadcast attempt is finished

    • closeGracefully

      public reactor.core.publisher.Mono<Void> closeGracefully()
      Initiates a graceful shutdown of the transport. This method:
      • Sets the closing flag to prevent new connections
      • Closes all active SSE connections
      • Removes all session records
      Specified by:
      closeGracefully in interface McpServerTransportProviderBase
      Returns:
      A Mono that completes when all cleanup operations are finished

    • getRouterFunction

      public org.springframework.web.servlet.function.RouterFunction<org.springframework.web.servlet.function.ServerResponse> getRouterFunction()
      Returns the RouterFunction that defines the HTTP endpoints for this transport. The router function handles two endpoints:
      • GET /sse - For establishing SSE connections
      • POST [messageEndpoint] - For receiving JSON-RPC messages from clients
      Returns:
      The configured RouterFunction for handling HTTP requests

    • builder

      public static WebMvcSseServerTransportProvider.Builder builder()
      Creates a new Builder instance for configuring and creating instances of WebMvcSseServerTransportProvider.
      Returns:
      A new Builder instance