Session Management

Session Management

MCP Catie implements session management to maintain continuity for client connections. This document explains how sessions work and how they affect request routing.

What are Sessions?

In the context of MCP, a session represents a continuous conversation between a client and a model. Sessions allow the model to maintain context across multiple requests.

MCP Catie tracks these sessions to ensure that all requests from the same conversation are routed to the same backend service.

Session Identification

Sessions are identified by the Mcp-Session-Id header in HTTP requests. This header is:

• Generated by the client
• Included in all requests that are part of the same conversation
• Used by MCP Catie to track which backend is handling the session

How Session Routing Works

1. When a client sends a request with a new session ID, MCP Catie routes it based on content (method and parameters)
2. The session ID is associated with the selected backend
3. All subsequent requests with the same session ID are routed to the same backend, regardless of content
4. If a session expires or is closed, the association is removed

Session Lifecycle

Sessions have a lifecycle managed by MCP Catie:

1. Creation: When a new session ID is seen
2. Active: While requests are being made with the session ID
3. Expiration: After a period of inactivity
4. Termination: When explicitly closed or when the backend becomes unavailable

Session Storage

MCP Catie stores session information in memory. The session store contains:

• Session ID
• Associated backend URL
• Last activity timestamp
• Session metadata

Session Headers

MCP Catie forwards several session-related headers to backend services:

• Mcp-Session-Id: The client's session identifier
• Mcp-Client-Id: The client's identifier (if provided)

These headers help backends track and manage sessions.

Session Consistency

Session consistency is critical for maintaining conversation context. MCP Catie ensures consistency by:

1. Always routing session requests to the same backend
2. Handling backend failures by marking sessions as terminated
3. Properly propagating session headers

Session Monitoring

You can monitor session activity through:

1. The monitoring UI at /stats, which shows active sessions
2. Logs, which record session creation, routing, and expiration
3. Metrics, which track session counts and durations

Best Practices

1. Unique Session IDs: Ensure clients generate unique session IDs
2. Session Reuse: Reuse session IDs for related requests
3. Expiration Tuning: Set expiration based on your use case