java-sdk

starts and manages a child MCP server process. During graceful shutdown, the SDK transport currently calls and waits for . That works when the child process responds to SIGTERM, but it can hang indefinitely if the child process ignores termination or becomes stuck. Downstream, we had to implement a custom to ensure proxied MCP server processes are always cleaned up when the parent shuts down. Current behavior The current shutdown flow is effectively: There is no configurable timeout and no fallback to . Expected behavior should support bounded process termination: 1. Stop accepting new messages. 2. Complete the transport sinks. 3. Send graceful termination with . 4. Wait up to a configurable timeout. 5. If the process is still alive, call . 6. Dispose the transport schedulers. This guarantees that child MCP server processes do not survive parent shutdown indefinitely. Proposed fix Add a configurable process termination timeout to , with a sensible default. Conceptually: This could be exposed through the existing builder or a dedicated constructor/builder option. Suggested regression test Add a test with a child process that ignores SIGTERM or does not exit promptly. The test should verify that: 1. completes within the configured timeout plus a small buffer. 2. The child process is no longer alive after completes. 3. The transport schedulers and sinks are cleaned up.

Add an optional, backward-compatible idle timeout to . The timeout is disabled by default. When configured, the provider records session activity and expires only sessions that have remained genuinely idle beyond the configured timeout. Active requests and open SSE streams keep their sessions alive. Motivation and Context Streamable HTTP sessions currently remain in the provider session map until the client sends an explicit request or the provider shuts down. Clients can disconnect, restart, or fail without sending , causing abandoned sessions to accumulate indefinitely. This implements the TTL and recency-marker approach discussed in #471 while preserving the existing default behavior. Fixes #471 How Has This Been Tested? 17 tests passed 0 failures 0 errors 394 tests passed 0 failures 0 errors 43 tests passed 0 failures 0 errors The focused timeout tests cover: cleanup disabled by default invalid timeout validation idle session expiration GET SSE stream activity replay GET activity context extraction failure POST activity refresh in-progress POST protection The branch was synchronized with the latest , preserving the upstream behavior and its HTTP 413 handling alongside session cleanup. No successful full-reactor test result is claimed. Breaking Changes None. Idle cleanup remains disabled unless is explicitly configured, and existing builder usage retains its previous behavior. Types of changes [x] Bug fix (non-breaking change which fixes an issue) [x] New feature (non-breaking change which adds functionality) [ ] Breaking change (fix or feature that would cause existing functionality to change) [ ] Documentation update Checklist [x] I have read the MCP Documentation [x] My code follows the repository's style guidelines [x] New and existing tests pass locally [x] I have added appropriate error handling [x] I have added or updated documentation as needed Additional context The implementation is limited to the servlet Streamable HTTP transport. External session storage and a global limit are outside this PR. is included as required by the repository contribution policy.

Summary The → HTTP 500 regression (unknown JSON-RPC method throws instead of returning ) currently has no remedy for users on the pre-2.0 release lines. The known fixes all target 2.0.x: #784 — "Stateless server handler throws exception instead of returning JSON-RPC -32601" — closed, milestoned to 2.0.1. #1072 — "[2026-07-28] Java SDK 2.0.0 returns HTTP 500 for OpenAI requests" — open, against 2.0.0; PR #1083 fixes the 2.0.x stateless transport. This issue asks for the fix to also be made available to users still on / . Why this matters for pre-2.0 users OpenAI's hosted MCP connector now sends during its handshake (before ). On the pre-2.0 SDK the stateless transport responds: OpenAI surfaces that 500 as HTTP 424 , which aborts the entire response — even for a plain "hi" that needs no tool call. In practice this takes an MCP server completely offline for the OpenAI Responses API connector the moment the client starts probing, with no application-side cause. The documented backward-compat behavior is to return so the client falls back to the legacy flow, and that fallback lives in the SDK's request handling, not in application code — so downstream apps cannot fix it without patching or replacing the SDK. The only forward path today is upgrading to 2.0.x. For Spring AI consumers that is not a version bump: 2.x requires Spring Boot 4 / Spring Framework 7, a framework-wide migration. Concretely, we are on (MCP Java SDK ) on Spring Boot 3.x, and a trial bump to 2.0 compiles and passes unit tests but fails to boot (, a Framework 7 class). So a spec-compatibility regression triggered by a client-side change is effectively gating a large, unrelated framework migration. The ask Either of the following would resolve it for pre-2.0 users: 1. Backport the / handling to a maintained pre-2.0 line and cut a patch release. This is consistent with lines the project already maintains — , , and all shipped in May–June 2026, so this is not asking to revive an EOL branch. 2. Or publish an officially documented interim compat handler for the stateless transport — i.e. a supported way to make unknown methods (notably ) return / a non-500 without upgrading. Consumers are currently doing this ad hoc with a servlet filter in front of the SDK; a documented, blessed pattern would be preferable to everyone reinventing it. Environment MCP Java SDK: (via ) Spring Boot 3.x / Spring Framework 6.2.x Client: OpenAI hosted MCP connector (Responses API), protocol revision References #784 (fix milestoned to 2.0.1) #1072 + PR #1083 (2.0.x server/discover 500 fix)