Package io.modelcontextprotocol.server.transport

Class WebMvcSseServerTransport

java.lang.Object
io.modelcontextprotocol.server.transport.WebMvcSseServerTransport
All Implemented Interfaces:
McpTransport, ServerMcpTransport
public class WebMvcSseServerTransport extends Object implements ServerMcpTransport
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 Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_SSE_ENDPOINT
    Default SSE endpoint path as specified by the MCP transport specification.
    static final String
    ENDPOINT_EVENT_TYPE
    Event type for sending the message endpoint URI to clients.
    static final String
    MESSAGE_EVENT_TYPE
    Event type for JSON-RPC messages sent through the SSE connection.

  • Constructor Summary

    Constructors
    Constructor
    Description
    WebMvcSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)
    Constructs a new WebMvcSseServerTransport instance with the default SSE endpoint.
    WebMvcSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)
    Constructs a new WebMvcSseServerTransport instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    reactor.core.publisher.Mono<Void>
    closeGracefully()
    Initiates a graceful shutdown of the transport.
    reactor.core.publisher.Mono<Void>
    connect(Function<reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>,reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>> connectionHandler)
    Sets up the message handler for this transport.
    org.springframework.web.servlet.function.RouterFunction<org.springframework.web.servlet.function.ServerResponse>
    getRouterFunction()
    Returns the RouterFunction that defines the HTTP endpoints for this transport.
    reactor.core.publisher.Mono<Void>
    sendMessage(McpSchema.JSONRPCMessage message)
    Broadcasts a message to all connected clients through their SSE connections.
    <T> T
    unmarshalFrom(Object data, com.fasterxml.jackson.core.type.TypeReference<T> typeRef)
    Converts data from one type to another using the configured ObjectMapper.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface io.modelcontextprotocol.spec.McpTransport

    close

  • 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

    • WebMvcSseServerTransport

      public WebMvcSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)
      Constructs a new WebMvcSseServerTransport 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.
      Throws:
      IllegalArgumentException - if either objectMapper or messageEndpoint is null

    • WebMvcSseServerTransport

      public WebMvcSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)
      Constructs a new WebMvcSseServerTransport 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

  • Method Details

    • connect

      public reactor.core.publisher.Mono<Void> connect(Function<reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>,reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>> connectionHandler)
      Sets up the message handler for this transport. In the WebMVC SSE implementation, this method only stores the handler for later use, as connections are initiated by clients rather than the server.
      Specified by:
      connect in interface McpTransport
      Parameters:
      connectionHandler - The function to process incoming JSON-RPC messages and produce responses
      Returns:
      An empty Mono since the server doesn't initiate connections

    • sendMessage

      public reactor.core.publisher.Mono<Void> sendMessage(McpSchema.JSONRPCMessage message)
      Broadcasts a message 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:
      sendMessage in interface McpTransport
      Parameters:
      message - The JSON-RPC message to broadcast to all connected clients
      Returns:
      A Mono that completes when the broadcast attempt is finished

    • 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 is particularly useful for handling complex JSON-RPC parameter types.
      Specified by:
      unmarshalFrom in interface McpTransport
      Type Parameters:
      T - The target type
      Parameters:
      data - The source data object to convert
      typeRef - The target type reference
      Returns:
      The converted object of type T

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