java-sdk/docs/ref-session.md

MCP Session Reference

McpSession Interface

org.springframework.ai.mcp.spec.McpSession

The MCP (Model Context Protocol) session components implement the MCP specification for managing bidirectional JSON-RPC communication between clients and model servers. The implementation provides a foundation for request-response patterns and notification handling, as well as managing the session lifecycle.

Overview

The session operates asynchronously using Project Reactor's Mono type for non-blocking operations. It supports both request-response patterns and one-way notifications.

Methods

Request-Response

<T> Mono<T> sendRequest(String method, Object requestParams, TypeReference<T> typeRef)

Sends a request to the model server and expects a response of type T.

Parameters:

• method: The name of the method to be called on the server
• requestParams: The parameters to be sent with the request
• typeRef: The TypeReference describing the expected response type

Returns:

• A Mono that will emit the response when received

Notification

Mono<Void> sendNotification(String method, Map<String, Object> params)

Sends a notification to the model server with parameters.

Parameters:

• method: The name of the notification method to be called on the server
• params: A map of parameters to be sent with the notification

Returns:

• A Mono that completes when the notification has been sent

Close Gracefully

Mono<Void> closeGracefully()

Closes the session and releases any associated resources asynchronously.

Returns:

• A Mono that completes when the session has been closed

Close

void close()

Closes the session and releases any associated resources synchronously.

DefaultMcpSession Implementation

The DefaultMcpSession provides the concrete implementation of the MCP session with the following key features:

1. Message Correlation

• Uses unique request IDs combining session UUID prefix and atomic counter
• Maintains thread-safe tracking of pending responses
• Implements timeout management for requests

2. Handler Registration

public interface RequestHandler {
    Mono<Object> handle(Object params);
}

public interface NotificationHandler {
    Mono<Void> handle(Object params);
}

Usage Example

McpSession session = // obtain session instance

// Send a request
TypeReference<ResponseType> typeRef = new TypeReference<ResponseType>() {};
Mono<ResponseType> response = session.sendRequest("method.name", requestParams, typeRef);

// Send a notification without parameters
Mono<Void> notificationResult = session.sendNotification("notification.method");

// Send a notification with parameters
Map<String, Object> params = new HashMap<>();
params.put("key", "value");
Mono<Void> paramNotificationResult = session.sendNotification("notification.method", params);

// Close the session gracefully
session.closeGracefully()
    .subscribe(
        null,
        error -> System.err.println("Error closing session: " + error),
        () -> System.out.println("Session closed successfully")
    );

Implementation Notes

• The interface is designed to be transport-agnostic, allowing different transport implementations (SSE, STDIO) to be used.
• All operations except close() are non-blocking and return Mono instances.
• The sendRequest method uses Jackson's TypeReference for type-safe deserialization of responses.
• The default implementation of sendNotification(String) delegates to sendNotification(String, Map) with null parameters.