René's URL Explorer Experiment


Title: feat(auth): proactive OAuth token refresh with jitter to reduce concurrent refresh spikes by Bartok9 · Pull Request #2859 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: feat(auth): proactive OAuth token refresh with jitter to reduce concurrent refresh spikes by Bartok9 · Pull Request #2859 · modelcontextprotocol/python-sdk

X Title: feat(auth): proactive OAuth token refresh with jitter to reduce concurrent refresh spikes by Bartok9 · Pull Request #2859 · modelcontextprotocol/python-sdk

Description: Summary Refresh OAuth tokens proactively at ~80% of their lifetime with a small random jitter, instead of only reactively once they've already expired. This reduces the "thundering herd" of simultaneous token refreshes that occurs when a fleet of OAuth-backed MCP connectors is provisioned around the same time. The production problem When many MCP clients each hold an OAuth connection and were provisioned (or last refreshed) in roughly the same window, their access tokens all expire inside the same narrow window too. Today refresh only fires after is_token_valid() returns False (i.e. after hard expiry), so all of those clients try to refresh at nearly the same moment. For a large fleet that produces a synchronized burst of grant_type=refresh_token requests against the authorization server — contention, rate-limit (429) responses, and spurious auth failures, all clustered into the same ~60s window. The herd then re-synchronizes on the new tokens and the spike repeats on the next cycle. The design Add a per-connection proactive refresh point that sits before hard expiry and is individually jittered, so a fleet desynchronizes naturally: refresh_at = now + expires_in * refresh_fraction - jitter refresh_fraction = 0.8 by default → refresh once 80% of the lifetime has elapsed, leaving headroom before hard expiry. jitter ∈ [0, 30s] by default, always subtracted so it can only pull the refresh point earlier — it can never push past hard expiry. Each connector draws its own jitter, so refreshes spread out across the window rather than bunching up. New pieces: calculate_token_refresh_time(expires_in, *, refresh_fraction=0.8, max_jitter_seconds=30.0, jitter=None) in src/mcp/shared/auth_utils.py — pure, deterministic-testable (inject jitter to bypass the RNG), returns None when expires_in is None. OAuthContext.token_refresh_time field, set alongside token_expiry_time in update_token_expiry and cleared in clear_tokens. OAuthContext.should_refresh_token() — True when we hold refreshable tokens and we're past the jittered proactive-refresh point, even if the token is still technically valid. async_auth_flow Phase 1 now refreshes when the token is hard-invalid OR should_refresh_token() is True (while can_refresh_token()), keeping the existing re-check / lock structure intact. is_token_valid() is deliberately unchanged — it still gates whether a token is usable at all (hard validity). Proactive refresh is layered on top. Edge cases handled expires_in is None → token_refresh_time is None; should_refresh_token() returns False and behavior degrades to the existing reactive path. Tiny TTLs (e.g. expires_in smaller than max_jitter_seconds): jitter is clamped to the available (refresh_at - now) window so the result never goes negative or before now. Never past hard expiry: the result is always clamped into (now, hard_expiry]. String expires_in (some servers return it as a string): handled via int() like calculate_token_expiry. Backward compatibility Fully backward compatible. No public signatures change; defaults preserve the current behavior shape (proactive refresh is strictly an improvement, not a breaking change). Clients that never got an expires_in keep the old reactive behavior exactly. Test coverage tests/shared/test_auth_utils.py — 9 new tests for calculate_token_refresh_time: normal TTL within the jitter window and strictly before hard expiry, None → None, string expires_in, deterministic injected jitter, jitter ordering (more jitter → earlier), never-past-hard-expiry across many TTLs, tiny-TTL no-negative, zero-TTL collapse, custom fraction. tests/client/test_auth.py — should_refresh_token() predicate (hard-valid-but-past-window → True; fresh → False; no refresh time → False; no refresh token → False), plus two async_auth_flow integration tests: one proving a proactive refresh request is yielded while the token is still hard-valid, and one proving a fresh token is used directly with no refresh. All tests/client/test_auth.py + tests/shared/test_auth_utils.py pass (128 passed, 1 xfailed). uv run ruff check, uv run ruff format --check, and uv run pyright are clean on all touched files. Relationship to #2858 This is complementary to and independent of #2858. That PR addresses concurrency/locking of refresh (narrowing the anyio.Lock scope + single-flight refresh_lock to fix a RuntimeError). This PR is purely about when a refresh fires (proactive + jittered), not how it's locked. They touch different concerns and compose cleanly; if #2858 lands first this will need only a trivial rebase. Credit Motivated by production feedback from @Ben-Home (CorpusIQ) on #2847. Refs #2847, #2858.

Open Graph Description: Summary Refresh OAuth tokens proactively at ~80% of their lifetime with a small random jitter, instead of only reactively once they've already expired. This reduces the "thundering herd&qu...

X Description: Summary Refresh OAuth tokens proactively at ~80% of their lifetime with a small random jitter, instead of only reactively once they've already expired. This reduces the "thundering...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2859

X: @github

direct link

Domain: github.com

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/:user_id/:repository/pull/:id/files(.:format)
route-controllerpull_requests
route-actionfiles
fetch-noncev2:e68bfaaa-6eea-c2ee-c988-6edb3b5922d1
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idD44A:37820D:1868212:205A78E:6B013555
html-safe-noncee599c7539ee85b5e6f474880a6dab68c41beb37a0be75110caa1b1200523dba6
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENDRBOjM3ODIwRDoxODY4MjEyOjIwNUE3OEU6NkIwMTM1NTUiLCJ2aXNpdG9yX2lkIjoiNjMyODI0NjczODg5NzQxNzU1NyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9
visitor-hmace578201b8166915edbc4558cbbdaefd4e0979e1f9a518a129432000bd3fdf3ee
hovercard-subject-tagpull_request:3860344255
github-keyboard-shortcutsrepository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///pull_requests/show/files
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/2859/files
twitter:imagehttps://avatars.githubusercontent.com/u/259807879?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/259807879?s=400&v=4
og:image:altSummary Refresh OAuth tokens proactively at ~80% of their lifetime with a small random jitter, instead of only reactively once they've already expired. This reduces the "thundering herd&qu...
og:site_nameGitHub
og:typeobject
hostnamegithub.com
expected-hostnamegithub.com
Nonecc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c
turbo-cache-controlno-preview
diff-viewunified
go-importgithub.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git
octolytics-dimension-user_id182288589
octolytics-dimension-user_loginmodelcontextprotocol
octolytics-dimension-repository_id862584018
octolytics-dimension-repository_nwomodelcontextprotocol/python-sdk
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id862584018
octolytics-dimension-repository_network_root_nwomodelcontextprotocol/python-sdk
turbo-body-classeslogged-out env-production page-responsive full-width
disable-turbotrue
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release8c77c9e8439031ad54c75a250694842892f693e1
ui-targetfull
theme-color#1e2327
color-schemelight dark

Links:

Skip to contenthttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F2859%2Ffiles
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F2859%2Ffiles
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=modelcontextprotocol%2Fpython-sdk
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
modelcontextprotocolhttps://github.com/modelcontextprotocol
python-sdkhttps://github.com/modelcontextprotocol/python-sdk
Codehttps://github.com/modelcontextprotocol/python-sdk
Issues315 (315)https://github.com/modelcontextprotocol/python-sdk/issues
Pull requests112 (112)https://github.com/modelcontextprotocol/python-sdk/pulls
Actionshttps://github.com/modelcontextprotocol/python-sdk/actions
Projectshttps://github.com/modelcontextprotocol/python-sdk/projects
Security and quality12 (12)https://github.com/modelcontextprotocol/python-sdk/security
Insightshttps://github.com/modelcontextprotocol/python-sdk/insights
Sign up for GitHub https://github.com/signup?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
terms of servicehttps://docs.github.com/terms
privacy statementhttps://docs.github.com/privacy
Sign inhttps://github.com/login?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
Bartok9https://github.com/Bartok9
modelcontextprotocol:mainhttps://github.com/modelcontextprotocol/python-sdk/tree/main
Bartok9:feat/oauth-proactive-refresh-jitterhttps://github.com/Bartok9/python-sdk/tree/feat/oauth-proactive-refresh-jitter
Conversation 2 https://github.com/modelcontextprotocol/python-sdk/pull/2859
Commits 2 https://github.com/modelcontextprotocol/python-sdk/pull/2859/commits
Checks 28 https://github.com/modelcontextprotocol/python-sdk/pull/2859/checks
Files changed https://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
feat(auth): proactive OAuth token refresh with jitter to reduce concurrent refresh spikes https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#top
Show all changes 2 commits https://github.com/modelcontextprotocol/python-sdk/pull/2859/files
b6da2c6 feat(auth): proactive OAuth token refresh with jitter to reduce concu… Bartok9 Jun 13, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/2859/commits/b6da2c607396970a430972903c1699257e7a7839
f8699ea fix(auth): drop stale no-cover pragmas on jitter clamp guards now exe… Bartok9 Jun 13, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/2859/commits/f8699eab8a8e40200c3e891089730d6576b2b080
Clear filters https://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
oauth2.py https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
auth_utils.py https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-fbdc8420ca151dd080002401442d8da9bee4df97f55498baf05f570990c97405
test_auth.py https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
test_auth_utils.py https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-756dfba56088748e16f4d23c41a507fbd7abdbfb164a99a747015d4f9a25bfc5
src/mcp/client/auth/oauth2.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
View file https://github.com/Bartok9/python-sdk/blob/f8699eab8a8e40200c3e891089730d6576b2b080/src/mcp/client/auth/oauth2.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/2859/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-b7aaf2062da175cea9a532176d6eb78b659eaadb757cc48929f0bafccfdb8d98
src/mcp/shared/auth_utils.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-fbdc8420ca151dd080002401442d8da9bee4df97f55498baf05f570990c97405
View file https://github.com/Bartok9/python-sdk/blob/f8699eab8a8e40200c3e891089730d6576b2b080/src/mcp/shared/auth_utils.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/2859/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-fbdc8420ca151dd080002401442d8da9bee4df97f55498baf05f570990c97405
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-fbdc8420ca151dd080002401442d8da9bee4df97f55498baf05f570990c97405
tests/client/test_auth.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
View file https://github.com/Bartok9/python-sdk/blob/f8699eab8a8e40200c3e891089730d6576b2b080/tests/client/test_auth.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/2859/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
https://github.com/modelcontextprotocol/python-sdk/pull/2859/files#diff-f083d075f463e8b1ecfa6b931c33288c3d09b00ee3af3e5f74df16b7e75c3ab1
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/2859/files
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.