From 2f15b5fb1d4d24f92d28d7d189059dbe0142a1ba Mon Sep 17 00:00:00 2001 From: Tin Chi Lo Date: Tue, 14 Jul 2026 20:52:39 -0700 Subject: [PATCH] fix(mcp): cap per-user OAuth token cache TTL at the token's own lifetime token_storage_ttl_seconds previously won outright over the token's expires_in, so a TTL longer than the token's lifetime kept the Redis fast path serving an expired bearer until eviction, while the stored refresh_token sat unused because refresh only runs on the DB read-through The configured TTL is now capped at expires_in minus the expiry buffer. Shorter TTLs and servers without the field behave exactly as before, and the TTL still applies verbatim when the upstream reports no expires_in. The dashboard tooltips on the create and edit forms are updated to describe the capped behavior --- .../mcp_server/oauth2_token_cache.py | 18 +++--- .../types/mcp_server/mcp_server_manager.py | 7 ++- .../mcp_server/test_oauth2_token_cache.py | 63 +++++++++++++++++++ .../_components/OAuthFormFields.tsx | 2 +- .../_components/mcp_server_edit.tsx | 2 +- 5 files changed, 79 insertions(+), 13 deletions(-) diff --git a/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py b/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py index 33f0641b732..43fe3999291 100644 --- a/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py +++ b/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py @@ -175,16 +175,18 @@ mcp_oauth2_token_cache = MCPOAuth2TokenCache() def _compute_per_user_token_ttl(server: "MCPServer", expires_in: Optional[int]) -> int: """Compute Redis TTL for a per-user token. - Uses server.token_storage_ttl_seconds when configured; otherwise derives - TTL from expires_in minus the expiry buffer; falls back to the default TTL. + Uses server.token_storage_ttl_seconds when configured, capped at the token's + remaining lifetime (expires_in minus the expiry buffer) so a cached entry never + outlives the token itself; otherwise derives TTL from expires_in minus the + expiry buffer; falls back to the default TTL. """ + lifetime_bound = expires_in - MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS if expires_in is not None else None if server.token_storage_ttl_seconds is not None: - return max(server.token_storage_ttl_seconds, 1) - if expires_in is not None: - return max( - expires_in - MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS, - 1, - ) + if lifetime_bound is None: + return max(server.token_storage_ttl_seconds, 1) + return max(min(server.token_storage_ttl_seconds, lifetime_bound), 1) + if lifetime_bound is not None: + return max(lifetime_bound, 1) return MCP_PER_USER_TOKEN_DEFAULT_TTL diff --git a/litellm/types/mcp_server/mcp_server_manager.py b/litellm/types/mcp_server/mcp_server_manager.py index 82ff15303f3..ced6dfe5e2e 100644 --- a/litellm/types/mcp_server/mcp_server_manager.py +++ b/litellm/types/mcp_server/mcp_server_manager.py @@ -122,9 +122,10 @@ class MCPServer(BaseModel): # response (supports dot-notation for nested fields, e.g. "team.enterprise_id"). # Tokens that fail validation are rejected before storage. token_validation: Optional[Dict[str, Any]] = None - # Optional TTL override (seconds) for the Redis per-user token cache. - # Defaults to the token's expires_in minus the expiry buffer, or - # MCP_PER_USER_TOKEN_DEFAULT_TTL when expires_in is absent. + # Optional TTL override (seconds) for the Redis per-user token cache, capped + # at the token's expires_in minus the expiry buffer so a cached entry never + # outlives the token. Defaults to the token's expires_in minus the expiry + # buffer, or MCP_PER_USER_TOKEN_DEFAULT_TTL when expires_in is absent. token_storage_ttl_seconds: Optional[int] = None timeout: Optional[float] = None # Max concurrent outbound tool calls to this server; excess calls queue. diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py index 7d2cf4442a5..47112fc9900 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py @@ -227,3 +227,66 @@ async def test_client_credentials_uses_client_secret_basic_when_configured(): assert "client_secret" not in kwargs["data"] assert "client_id" not in kwargs["data"] assert kwargs["data"]["grant_type"] == "client_credentials" + + +def test_storage_ttl_capped_at_token_lifetime(): + """A token_storage_ttl_seconds longer than the token's own lifetime must be capped at + expires_in minus the expiry buffer. Before the cap, the configured TTL won outright and the + Redis fast path (which never re-checks expires_at) kept serving the dead token until eviction, + while the stored refresh_token sat unused because refresh only runs on the DB read-through.""" + from litellm.constants import MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS + from litellm.proxy._experimental.mcp_server.oauth2_token_cache import ( + _compute_per_user_token_ttl, + ) + + server = _server(oauth2_flow=None, token_storage_ttl_seconds=604800) + assert _compute_per_user_token_ttl(server, expires_in=86400) == 86400 - MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS + + +def test_storage_ttl_shorter_than_token_lifetime_wins(): + """A configured TTL below the token lifetime is the operative value: the knob's purpose is to + force earlier DB re-checks (staleness backstop), so the shorter side must win the min().""" + from litellm.proxy._experimental.mcp_server.oauth2_token_cache import ( + _compute_per_user_token_ttl, + ) + + server = _server(oauth2_flow=None, token_storage_ttl_seconds=3600) + assert _compute_per_user_token_ttl(server, expires_in=86400) == 3600 + + +def test_storage_ttl_verbatim_when_token_lifetime_unknown(): + """With no expires_in from the upstream there is nothing to cap against, so the configured + TTL applies as-is (matching the pre-cap behavior for lifetime-less tokens).""" + from litellm.proxy._experimental.mcp_server.oauth2_token_cache import ( + _compute_per_user_token_ttl, + ) + + server = _server(oauth2_flow=None, token_storage_ttl_seconds=604800) + assert _compute_per_user_token_ttl(server, expires_in=None) == 604800 + + +def test_storage_ttl_floors_at_one_second_for_nearly_dead_token(): + """A token already inside the expiry buffer yields the 1-second floor, not zero or a negative + TTL, mirroring the floor the default (unconfigured) path has always had.""" + from litellm.proxy._experimental.mcp_server.oauth2_token_cache import ( + _compute_per_user_token_ttl, + ) + + server = _server(oauth2_flow=None, token_storage_ttl_seconds=3600) + assert _compute_per_user_token_ttl(server, expires_in=30) == 1 + + +def test_default_ttl_paths_unchanged_without_storage_ttl(): + """With token_storage_ttl_seconds unset the TTL still derives from expires_in minus the + buffer, and falls back to MCP_PER_USER_TOKEN_DEFAULT_TTL when expires_in is absent.""" + from litellm.constants import ( + MCP_PER_USER_TOKEN_DEFAULT_TTL, + MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS, + ) + from litellm.proxy._experimental.mcp_server.oauth2_token_cache import ( + _compute_per_user_token_ttl, + ) + + server = _server(oauth2_flow=None) + assert _compute_per_user_token_ttl(server, expires_in=86400) == 86400 - MCP_PER_USER_TOKEN_EXPIRY_BUFFER_SECONDS + assert _compute_per_user_token_ttl(server, expires_in=None) == MCP_PER_USER_TOKEN_DEFAULT_TTL diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/OAuthFormFields.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/OAuthFormFields.tsx index f359bdee065..fc72981edd0 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/OAuthFormFields.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/OAuthFormFields.tsx @@ -228,7 +228,7 @@ const OAuthFormFields: React.FC = ({ label={ } name="token_storage_ttl_seconds" diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx index 3b184cc6f1e..455fe69455d 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/mcp_server_edit.tsx @@ -1386,7 +1386,7 @@ const MCPServerEdit: React.FC = ({ label={ Token Storage TTL (seconds, optional) - +