Module io.modelcontextprotocol.sdk.mcp

Package io.modelcontextprotocol.server.transport

Class HttpServletSseServerTransportProvider

java.lang.Object

jakarta.servlet.GenericServlet

jakarta.servlet.http.HttpServlet

io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider

All Implemented Interfaces:

McpServerTransportProvider, jakarta.servlet.Servlet, jakarta.servlet.ServletConfig, Serializable

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

A Servlet-based implementation of the MCP HTTP with Server-Sent Events (SSE) transport specification. This implementation provides similar functionality to WebFluxSseServerTransportProvider 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:

• McpServerTransportProvider
• HttpServlet
• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	HttpServletSseServerTransportProvider.Builder	Builder for creating instances of HttpServletSseServerTransportProvider.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	APPLICATION_JSON
static final String	DEFAULT_BASE_URL
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
HttpServletSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint)	Creates a new HttpServletSseServerTransportProvider instance with the default SSE endpoint.
HttpServletSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint)	Creates a new HttpServletSseServerTransportProvider instance with a custom SSE endpoint.
HttpServletSseServerTransportProvider(com.fasterxml.jackson.databind.ObjectMapper objectMapper, String baseUrl, String messageEndpoint, String sseEndpoint)	Creates a new HttpServletSseServerTransportProvider instance with a custom SSE endpoint.

Method Summary

Modifier and Type	Method	Description
static HttpServletSseServerTransportProvider.Builder	builder()	Creates a new Builder instance for configuring and creating instances of HttpServletSseServerTransportProvider.
reactor.core.publisher.Mono<Void>	closeGracefully()	Initiates a graceful shutdown of the transport.
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>	notifyClients(String method, Object params)	Broadcasts a notification to all connected clients.
void	setSessionFactory(McpServerSession.Factory sessionFactory)	Sets the session factory for creating new sessions.

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

Methods inherited from interface io.modelcontextprotocol.spec.McpServerTransportProvider

close

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

DEFAULT_BASE_URL

public static final String DEFAULT_BASE_URL

See Also:

• Constant Field Values

Constructor Details

HttpServletSseServerTransportProvider

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

Creates a new HttpServletSseServerTransportProvider 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

HttpServletSseServerTransportProvider

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

Creates a new HttpServletSseServerTransportProvider instance with a custom SSE endpoint.

Parameters:

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

baseUrl - The base URL for the server transport

messageEndpoint - The endpoint path where clients will send their messages

sseEndpoint - The endpoint path where clients will establish SSE connections

HttpServletSseServerTransportProvider

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

Creates a new HttpServletSseServerTransportProvider 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

setSessionFactory

public void setSessionFactory(McpServerSession.Factory sessionFactory)

Sets the session factory for creating new sessions.

Specified by:

setSessionFactory in interface McpServerTransportProvider

Parameters:

sessionFactory - The session factory to use

notifyClients

public reactor.core.publisher.Mono<Void> notifyClients(String method,
 Object params)

Broadcasts a notification to all connected clients.

Specified by:

notifyClients in interface McpServerTransportProvider

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

See Also:

• McpSession.sendNotification(String, Map)

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 session handler, 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

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 McpServerTransportProvider

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

builder

public static HttpServletSseServerTransportProvider.Builder builder()

Creates a new Builder instance for configuring and creating instances of HttpServletSseServerTransportProvider.

Returns:

A new Builder instance