Skip to content

Commit b9666ad

Browse files
bdshadowclaude
andcommitted
fix: sync MCP sessions to Redis for multi-replica deployments
WebMvcStreamableServerTransportProvider stores sessions in an in-memory ConcurrentHashMap, causing 404 "Session not found" errors when requests scatter across replicas. Add a servlet filter that persists session metadata to Redis and reconstructs sessions on replicas that haven't seen the client. Tracked upstream: modelcontextprotocol/java-sdk#201 Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent 007f2f6 commit b9666ad

5 files changed

Lines changed: 376 additions & 1 deletion

File tree

‎backend/app/build.gradle‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ dependencies {
139139
implementation "org.springframework.boot:spring-boot-properties-migrator"
140140

141141
implementation libs.springDocOpenApiCommon
142-
testApi libs.redissonSpringBootStarter
142+
implementation libs.redissonSpringBootStarter
143143

144144
/**
145145
* OPENTELEMETRY

‎backend/app/src/main/kotlin/io/tolgee/mcp/McpConfig.kt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
package io.tolgee.mcp
22

3+
import com.fasterxml.jackson.databind.ObjectMapper
34
import io.modelcontextprotocol.server.McpServer
45
import io.modelcontextprotocol.server.McpSyncServer
56
import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider
67
import io.modelcontextprotocol.spec.McpSchema
78
import io.tolgee.util.VersionProvider
9+
import org.redisson.api.RedissonClient
10+
import org.springframework.boot.web.servlet.FilterRegistrationBean
811
import org.springframework.context.annotation.Bean
912
import org.springframework.context.annotation.Configuration
1013
import org.springframework.web.servlet.function.RouterFunction
@@ -50,4 +53,16 @@ class McpConfig {
5053
): RouterFunction<ServerResponse> {
5154
return transportProvider.routerFunction
5255
}
56+
57+
@Bean
58+
fun mcpSessionRedisFilter(
59+
transportProvider: WebMvcStreamableServerTransportProvider,
60+
redissonClient: RedissonClient?,
61+
objectMapper: ObjectMapper,
62+
): FilterRegistrationBean<McpSessionRedisFilter> {
63+
val filter = McpSessionRedisFilter(transportProvider, redissonClient, objectMapper)
64+
val registration = FilterRegistrationBean(filter)
65+
registration.addUrlPatterns("/mcp/*")
66+
return registration
67+
}
5368
}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
package io.tolgee.mcp
2+
3+
data class McpSessionData(
4+
val clientCapabilitiesJson: String?,
5+
val clientInfoJson: String?,
6+
)
Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
package io.tolgee.mcp
2+
3+
import com.fasterxml.jackson.databind.ObjectMapper
4+
import io.modelcontextprotocol.server.McpNotificationHandler
5+
import io.modelcontextprotocol.server.McpRequestHandler
6+
import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider
7+
import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory
8+
import io.modelcontextprotocol.spec.McpSchema
9+
import io.modelcontextprotocol.spec.McpStreamableServerSession
10+
import jakarta.servlet.FilterChain
11+
import jakarta.servlet.http.HttpServletRequest
12+
import jakarta.servlet.http.HttpServletResponse
13+
import jakarta.servlet.http.HttpServletResponseWrapper
14+
import org.redisson.api.RedissonClient
15+
import org.slf4j.LoggerFactory
16+
import org.springframework.web.filter.OncePerRequestFilter
17+
import java.time.Duration
18+
import java.util.concurrent.ConcurrentHashMap
19+
20+
/**
21+
* Servlet filter that syncs MCP sessions to Redis for multi-replica deployments.
22+
*
23+
* The MCP Java SDK's [WebMvcStreamableServerTransportProvider] stores sessions in an in-memory
24+
* `ConcurrentHashMap`. When running multiple replicas behind a load balancer, requests with an
25+
* `Mcp-Session-Id` header may land on a replica that doesn't have the session, resulting in
26+
* 404 "Session not found" errors.
27+
*
28+
* This filter works around the issue by:
29+
* - **Before handler**: If the request carries an `Mcp-Session-Id` not present in the local map,
30+
* reconstructs the session from Redis and injects it into the transport provider's sessions map.
31+
* - **After handler**: If the response sets a new `Mcp-Session-Id` (initialize), persists the
32+
* session metadata to Redis.
33+
*
34+
* Uses reflection because [WebMvcStreamableServerTransportProvider] has a private constructor and
35+
* all private fields/methods — it cannot be extended or configured with custom session storage.
36+
*
37+
* When Redis is unavailable (e.g. single-instance deployment), the filter is a no-op.
38+
*
39+
* This is a temporary workaround until the SDK provides a proper session storage API.
40+
* Tracked upstream: https://github.com/modelcontextprotocol/java-sdk/issues/201
41+
* SDK maintainer confirmed persistent session storage is planned:
42+
* https://github.com/modelcontextprotocol/java-sdk/issues/201#issuecomment-3915069460
43+
*/
44+
class McpSessionRedisFilter(
45+
private val transportProvider: WebMvcStreamableServerTransportProvider,
46+
private val redissonClient: RedissonClient?,
47+
private val objectMapper: ObjectMapper,
48+
) : OncePerRequestFilter() {
49+
private val log = LoggerFactory.getLogger(McpSessionRedisFilter::class.java)
50+
51+
private val sessionsMap: ConcurrentHashMap<String, McpStreamableServerSession> by lazy {
52+
loadSessionsMap()
53+
}
54+
55+
private val factoryFields: FactoryFields by lazy {
56+
loadFactoryFields()
57+
}
58+
59+
override fun doFilterInternal(
60+
request: HttpServletRequest,
61+
response: HttpServletResponse,
62+
filterChain: FilterChain,
63+
) {
64+
if (redissonClient == null) {
65+
filterChain.doFilter(request, response)
66+
return
67+
}
68+
69+
val sessionId = request.getHeader(MCP_SESSION_ID_HEADER)
70+
71+
// Pre-handle: recover session from Redis if not in local map
72+
if (sessionId != null && !sessionsMap.containsKey(sessionId)) {
73+
recoverSessionFromRedis(sessionId)
74+
}
75+
76+
// Wrap response to capture new session ID from initialize responses
77+
val responseWrapper = SessionIdCapturingResponseWrapper(response)
78+
filterChain.doFilter(request, responseWrapper)
79+
80+
// Post-handle: persist new session to Redis
81+
val newSessionId = responseWrapper.capturedSessionId
82+
if (newSessionId != null) {
83+
persistSessionToRedis(newSessionId)
84+
}
85+
}
86+
87+
private fun recoverSessionFromRedis(sessionId: String) {
88+
try {
89+
val bucket = redissonClient!!.getBucket<String>("$REDIS_KEY_PREFIX$sessionId")
90+
val json = bucket.get() ?: return
91+
92+
val sessionData = objectMapper.readValue(json, McpSessionData::class.java)
93+
94+
val clientCapabilities =
95+
sessionData.clientCapabilitiesJson?.let {
96+
objectMapper.readValue(it, McpSchema.ClientCapabilities::class.java)
97+
}
98+
val clientInfo =
99+
sessionData.clientInfoJson?.let {
100+
objectMapper.readValue(it, McpSchema.Implementation::class.java)
101+
}
102+
103+
@Suppress("UNCHECKED_CAST")
104+
val session =
105+
McpStreamableServerSession(
106+
sessionId,
107+
clientCapabilities,
108+
clientInfo,
109+
factoryFields.requestTimeout,
110+
factoryFields.requestHandlers as Map<String, McpRequestHandler<*>>,
111+
factoryFields.notificationHandlers as Map<String, McpNotificationHandler>,
112+
)
113+
114+
sessionsMap[sessionId] = session
115+
log.debug("Recovered MCP session {} from Redis", sessionId)
116+
} catch (e: Exception) {
117+
log.warn("Failed to recover MCP session {} from Redis", sessionId, e)
118+
}
119+
}
120+
121+
private fun persistSessionToRedis(sessionId: String) {
122+
try {
123+
val session = sessionsMap[sessionId] ?: return
124+
125+
val clientCapabilities = getPrivateField<Any?>(session, "clientCapabilities")
126+
val clientInfo = getPrivateField<Any?>(session, "clientInfo")
127+
128+
val capabilitiesValue = unwrapField(clientCapabilities, "clientCapabilities")
129+
val infoValue = unwrapField(clientInfo, "clientInfo")
130+
131+
val sessionData =
132+
McpSessionData(
133+
clientCapabilitiesJson = capabilitiesValue?.let { objectMapper.writeValueAsString(it) },
134+
clientInfoJson = infoValue?.let { objectMapper.writeValueAsString(it) },
135+
)
136+
137+
val bucket = redissonClient!!.getBucket<String>("$REDIS_KEY_PREFIX$sessionId")
138+
bucket.set(objectMapper.writeValueAsString(sessionData), SESSION_TTL)
139+
log.debug("Persisted MCP session {} to Redis", sessionId)
140+
} catch (e: Exception) {
141+
log.warn("Failed to persist MCP session {} to Redis", sessionId, e)
142+
}
143+
}
144+
145+
private fun unwrapField(
146+
fieldValue: Any?,
147+
fieldName: String,
148+
): Any? {
149+
if (fieldValue == null) return null
150+
if (fieldValue is java.util.concurrent.atomic.AtomicReference<*>) {
151+
return fieldValue.get()
152+
}
153+
log.warn(
154+
"Expected AtomicReference for field '{}' but got {}; using value directly",
155+
fieldName,
156+
fieldValue.javaClass.name,
157+
)
158+
return fieldValue
159+
}
160+
161+
@Suppress("UNCHECKED_CAST")
162+
private fun loadSessionsMap(): ConcurrentHashMap<String, McpStreamableServerSession> {
163+
val field = WebMvcStreamableServerTransportProvider::class.java.getDeclaredField("sessions")
164+
field.isAccessible = true
165+
return field.get(transportProvider) as ConcurrentHashMap<String, McpStreamableServerSession>
166+
}
167+
168+
private fun loadFactoryFields(): FactoryFields {
169+
val factoryField = WebMvcStreamableServerTransportProvider::class.java.getDeclaredField("sessionFactory")
170+
factoryField.isAccessible = true
171+
val factory = factoryField.get(transportProvider)
172+
173+
if (factory !is DefaultMcpStreamableServerSessionFactory) {
174+
throw IllegalStateException(
175+
"Expected DefaultMcpStreamableServerSessionFactory but got ${factory?.javaClass?.name}",
176+
)
177+
}
178+
179+
val timeoutField = DefaultMcpStreamableServerSessionFactory::class.java.getDeclaredField("requestTimeout")
180+
timeoutField.isAccessible = true
181+
val requestTimeout = timeoutField.get(factory) as Duration
182+
183+
val handlersField = DefaultMcpStreamableServerSessionFactory::class.java.getDeclaredField("requestHandlers")
184+
handlersField.isAccessible = true
185+
186+
@Suppress("UNCHECKED_CAST")
187+
val requestHandlers = handlersField.get(factory) as Map<String, Any>
188+
189+
val notifField = DefaultMcpStreamableServerSessionFactory::class.java.getDeclaredField("notificationHandlers")
190+
notifField.isAccessible = true
191+
192+
@Suppress("UNCHECKED_CAST")
193+
val notificationHandlers = notifField.get(factory) as Map<String, Any>
194+
195+
return FactoryFields(requestTimeout, requestHandlers, notificationHandlers)
196+
}
197+
198+
@Suppress("UNCHECKED_CAST")
199+
private fun <T> getPrivateField(
200+
obj: Any,
201+
fieldName: String,
202+
): T {
203+
val field = obj.javaClass.getDeclaredField(fieldName)
204+
field.isAccessible = true
205+
return field.get(obj) as T
206+
}
207+
208+
private class SessionIdCapturingResponseWrapper(
209+
response: HttpServletResponse,
210+
) : HttpServletResponseWrapper(response) {
211+
var capturedSessionId: String? = null
212+
private set
213+
214+
override fun setHeader(
215+
name: String,
216+
value: String?,
217+
) {
218+
if (name == MCP_SESSION_ID_HEADER && value != null) {
219+
capturedSessionId = value
220+
}
221+
super.setHeader(name, value)
222+
}
223+
224+
override fun addHeader(
225+
name: String,
226+
value: String?,
227+
) {
228+
if (name == MCP_SESSION_ID_HEADER && value != null) {
229+
capturedSessionId = value
230+
}
231+
super.addHeader(name, value)
232+
}
233+
}
234+
235+
private data class FactoryFields(
236+
val requestTimeout: Duration,
237+
val requestHandlers: Map<String, Any>,
238+
val notificationHandlers: Map<String, Any>,
239+
)
240+
241+
companion object {
242+
private const val MCP_SESSION_ID_HEADER = "Mcp-Session-Id"
243+
private const val REDIS_KEY_PREFIX = "mcp_session:"
244+
private val SESSION_TTL = Duration.ofHours(48)
245+
}
246+
}

0 commit comments

Comments
 (0)