Skip to content

feat: add custom reconnection scheduler for non-persistent environments #1177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: add custom reconnection scheduler for non-persistent environments #1177

wants to merge 2 commits into from

Conversation

@CHOIJEWON
Copy link

@CHOIJEWON CHOIJEWON commented Nov 27, 2025 •
edited
Loading

Resolves #1162

Summary

Adds support for custom reconnection scheduling to StreamableHTTPClientTransport, enabling proper reconnection handling in non-persistent environments like serverless functions, mobile apps, and desktop applications where setTimeout is insufficient or unavailable.

Motivation and Context

As discussed in #1162 and the review feedback from PR #1129, the current _scheduleReconnection method relies on setTimeout, which doesn't work well for:

  • Serverless/Edge Functions: Functions terminate before timers fire, requiring immediate reconnection on next invocation
  • Mobile Apps: Need platform-specific background scheduling (iOS Background Fetch, Android WorkManager)
  • Desktop Apps: Must handle sleep/wake cycles and power management
  • Non-persistent clients: Any environment where continuous timer-based scheduling is not viable

This PR implements the custom scheduler approach (option 2 from the original issue), providing maximum flexibility while maintaining full backward compatibility.

How Has This Been Tested?

  • src/client/streamableHttp.test.ts: Added comprehensive test suite with 4 new test cases:
    1. Custom scheduler usage: Verifies scheduler is called and reconnection occurs
    2. Parameter validation: Confirms correct delay and attempt count are passed
    3. Default fallback: Ensures setTimeout is used when no scheduler provided
    4. Serverless scenario: Tests deferred reconnection pattern for true serverless environments

Breaking Changes

None. This is a fully backward-compatible addition:

  • When reconnectionScheduler is not provided, the transport uses the default setTimeout-based scheduler
  • All existing code continues to work without modifications
  • No changes to existing public APIs

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Review Notes

This is one of my early contributions to the project. I've followed the existing patterns and conventions to the best of my ability,
but I'm very open to feedback on:

  • API design and naming conventions
  • Implementation patterns that better fit the SDK's architecture
  • Any improvements to tests or documentation

Thank you for taking the time to review 🙌

@CHOIJEWON
feat: add custom reconnection scheduler for non-persistent environments
307e536 
  Resolves modelcontextprotocol#1162

  Adds support for custom reconnection scheduling to StreamableHTTPClientTransport,
  enabling proper reconnection handling in non-persistent environments like
  serverless functions, mobile apps, and desktop applications.

  Changes:
  - Add ReconnectionScheduler type and 
econnectionScheduler option to transport
  - Refactor _scheduleReconnection to support custom scheduling logic
  - Maintain backward compatibility with default setTimeout-based scheduling
  - Add comprehensive test coverage for custom scheduler scenarios
  - Add detailed documentation with practical examples for:
    - Serverless environments (immediate and deferred reconnection)
    - Mobile apps (platform-specific background scheduling)
    - Desktop apps (power management and sleep/wake handling)

  The custom scheduler receives three parameters:
  - reconnect: callback to initiate reconnection
  - delay: suggested delay in milliseconds
  - attemptCount: current reconnection attempt count

  When no custom scheduler is provided, the default setTimeout behavior
  is preserved, ensuring full backward compatibility
@CHOIJEWON CHOIJEWON requested a review from a team as a code owner November 27, 2025 02:11
@pkg-pr-new
Copy link

pkg-pr-new bot commented Nov 27, 2025 •
edited
Loading

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1177

commit: a2fc4d8

@CHOIJEWON
Copy link
Author

CHOIJEWON commented Dec 1, 2025 •
edited
Loading

@felixweinberger

Sorry for tagging you — I know you’re busy.
I’ve created a PR addressing the issue you recently opened: “Allow customizable reconnection behavior for non-persistent clients (#1162)”.
It may still have some rough edges, but I would really appreciate it if you could take a look and share your feedback when you have time. 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Allow customizable reconnection behavior for non-persistent clients

1 participant

@CHOIJEWON