Package io.modelcontextprotocol.server.transport

Class HttpServletSseServerTransport

java.lang.Object

jakarta.servlet.GenericServlet

jakarta.servlet.http.HttpServlet

io.modelcontextprotocol.server.transport.HttpServletSseServerTransport

All Implemented Interfaces:

McpTransport, ServerMcpTransport, jakarta.servlet.Servlet, jakarta.servlet.ServletConfig, Serializable

@WebServlet(asyncSupported=true)
public class HttpServletSseServerTransport
extends jakarta.servlet.http.HttpServlet
implements ServerMcpTransport

A Servlet-based implementation of the MCP HTTP with Server-Sent Events (SSE) transport specification. This implementation provides similar functionality to WebFluxSseServerTransport but uses the traditional Servlet API instead of WebFlux.

The transport handles two types of endpoints:

• SSE endpoint (/sse) - Establishes a long-lived connection for server-to-client events
• Message endpoint (configurable) - Handles client-to-server message requests

Features:

• Asynchronous message handling using Servlet 6.0 async support
• Session management for multiple client connections
• Graceful shutdown support
• Error handling and response formatting

Author:

Christian Tzolov, Alexandros Pappas

See Also:

• ServerMcpTransport
• HttpServlet
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	APPLICATION_JSON
static final String	DEFAULT_SSE_ENDPOINT	Default endpoint path for SSE connections
static final String	ENDPOINT_EVENT_TYPE	Event type for endpoint information
static final String	FAILED_TO_SEND_ERROR_RESPONSE
static final String	MESSAGE_EVENT_TYPE	Event type for regular messages
static final String	UTF_8

Fields inherited from class jakarta.servlet.http.HttpServlet

LEGACY_DO_HEAD

Constructor Summary

Constructors

Constructor	Description
HttpServletSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)	Creates a new HttpServletSseServerTransport instance with the default SSE endpoint.
HttpServletSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)	Creates a new HttpServletSseServerTransport instance with a custom SSE endpoint.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the transport.
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>> handler)	Sets up the message handler for processing client requests.
void	destroy()	Cleans up resources when the servlet is being destroyed.
protected void	doGet(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)	Handles GET requests to establish SSE connections.
protected void	doPost(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)	Handles POST requests for client messages.
reactor.core.publisher.Mono<Void>	sendMessage(McpSchema.JSONRPCMessage message)	Broadcasts a message to all connected clients.
<T> T	unmarshalFrom(Object data, com.fasterxml.jackson.core.type.TypeReference<T> typeRef)	Unmarshals data from one type to another using the object mapper.

Methods inherited from class jakarta.servlet.http.HttpServlet

doDelete, doHead, doOptions, doPatch, doPut, doTrace, getLastModified, init, isSensitiveHeader, service, service

Methods inherited from class jakarta.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Field Details

UTF_8

public static final String UTF_8

See Also:

• Constant Field Values

APPLICATION_JSON

public static final String APPLICATION_JSON

See Also:

• Constant Field Values

FAILED_TO_SEND_ERROR_RESPONSE

public static final String FAILED_TO_SEND_ERROR_RESPONSE

See Also:

• Constant Field Values

DEFAULT_SSE_ENDPOINT

public static final String DEFAULT_SSE_ENDPOINT

Default endpoint path for SSE connections

See Also:

• Constant Field Values

MESSAGE_EVENT_TYPE

public static final String MESSAGE_EVENT_TYPE

Event type for regular messages

See Also:

• Constant Field Values

ENDPOINT_EVENT_TYPE

public static final String ENDPOINT_EVENT_TYPE

Event type for endpoint information

See Also:

• Constant Field Values

Constructor Details

HttpServletSseServerTransport

public HttpServletSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper,
 String messageEndpoint,
 String sseEndpoint)

Creates a new HttpServletSseServerTransport instance with a custom SSE endpoint.

Parameters:

objectMapper - The JSON object mapper to use for message serialization/deserialization

messageEndpoint - The endpoint path where clients will send their messages

sseEndpoint - The endpoint path where clients will establish SSE connections

HttpServletSseServerTransport

public HttpServletSseServerTransport(com.fasterxml.jackson.databind.ObjectMapper objectMapper,
 String messageEndpoint)

Creates a new HttpServletSseServerTransport instance with the default SSE endpoint.

Parameters:

objectMapper - The JSON object mapper to use for message serialization/deserialization

messageEndpoint - The endpoint path where clients will send their messages

Method Details

doGet

protected void doGet(jakarta.servlet.http.HttpServletRequest request,
 jakarta.servlet.http.HttpServletResponse response)
              throws jakarta.servlet.ServletException,
IOException

Handles GET requests to establish SSE connections.

This method sets up a new SSE connection when a client connects to the SSE endpoint. It configures the response headers for SSE, creates a new session, and sends the initial endpoint information to the client.

Overrides:

doGet in class jakarta.servlet.http.HttpServlet

Parameters:

request - The HTTP servlet request

response - The HTTP servlet response

Throws:

jakarta.servlet.ServletException - If a servlet-specific error occurs

IOException - If an I/O error occurs

doPost

protected void doPost(jakarta.servlet.http.HttpServletRequest request,
 jakarta.servlet.http.HttpServletResponse response)
               throws jakarta.servlet.ServletException,
IOException

Handles POST requests for client messages.

This method processes incoming messages from clients, routes them through the connect handler if configured, and sends back the appropriate response. It handles error cases and formats error responses according to the MCP specification.

Overrides:

doPost in class jakarta.servlet.http.HttpServlet

Parameters:

request - The HTTP servlet request

response - The HTTP servlet response

Throws:

jakarta.servlet.ServletException - If a servlet-specific error occurs

IOException - If an I/O error occurs

connect

public reactor.core.publisher.Mono<Void> connect(Function<reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>,reactor.core.publisher.Mono<McpSchema.JSONRPCMessage>> handler)

Sets up the message handler for processing client requests.

Specified by:

connect in interface McpTransport

Parameters:

handler - The function to process incoming messages and produce responses

Returns:

A Mono that completes when the handler is set up

sendMessage

public reactor.core.publisher.Mono<Void> sendMessage(McpSchema.JSONRPCMessage message)

Broadcasts a message to all connected clients.

This method serializes the message and sends it to all active client sessions. If a client is disconnected, its session is removed.

Specified by:

sendMessage in interface McpTransport

Parameters:

message - The message to broadcast

Returns:

A Mono that completes when the message has been sent to all clients

close

public void close()

Closes the transport.

This implementation delegates to the super class's close method.

Specified by:

close in interface McpTransport

unmarshalFrom

public <T> T unmarshalFrom(Object data,
 com.fasterxml.jackson.core.type.TypeReference<T> typeRef)

Unmarshals data from one type to another using the object mapper.

Specified by:

unmarshalFrom in interface McpTransport

Type Parameters:

T - The target type

Parameters:

data - The source data

typeRef - The type reference for the target type

Returns:

The unmarshaled data

closeGracefully

public reactor.core.publisher.Mono<Void> closeGracefully()

Initiates a graceful shutdown of the transport.

This method marks the transport as closing and closes all active client sessions. New connection attempts will be rejected during shutdown.

Specified by:

closeGracefully in interface McpTransport

Returns:

A Mono that completes when all sessions have been closed

destroy

public void destroy()

Cleans up resources when the servlet is being destroyed.

This method ensures a graceful shutdown by closing all client connections before calling the parent's destroy method.

Specified by:

destroy in interface jakarta.servlet.Servlet

Overrides:

destroy in class jakarta.servlet.GenericServlet