ContextQMD
Back to Fastmcp

token_cache

docs/python-sdk/fastmcp-utilities-token_cache.mdx

3.2.42.8 KB
Original Source

fastmcp.utilities.token_cache

In-memory cache for token verification results.

Provides a generic TTL-based cache for AccessToken objects, designed to reduce repeated network calls during opaque-token verification. Only successful verifications should be cached; errors and failures must be retried on every request.

Example: ```python from fastmcp.utilities.token_cache import TokenCache

cache = TokenCache(ttl_seconds=300, max_size=10000)

# On cache miss, call the upstream verifier and store the result.
hit, token = cache.get(raw_token)
if not hit:
    token = await _call_upstream(raw_token)
    if token is not None:
        cache.set(raw_token, token)
```

Classes

TokenCache <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

TTL-based in-memory cache for AccessToken objects.

Features:

  • SHA-256 hashed cache keys (fixed size, regardless of token length).
  • Per-entry TTL that respects both the configured ttl_seconds and the token's own expires_at claim (whichever is sooner).
  • Bounded size with FIFO eviction when the cache is full.
  • Periodic cleanup of expired entries to prevent unbounded growth.
  • Defensive deep copies on both store and retrieve to prevent callers from mutating cached values.

Caching is disabled when ttl_seconds is None or 0, or when max_size is 0. Negative values raise ValueError.

Methods:

enabled <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

python
enabled(self) -> bool

Return whether caching is active.

get <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

python
get(self, token: str) -> tuple[bool, AccessToken | None]

Look up a cached verification result.

Returns:

  • (True, AccessToken) on a cache hit, (False, None) on a miss
  • or when caching is disabled. The returned AccessToken is a deep
  • copy that is safe to mutate.

set <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

python
set(self, token: str, result: AccessToken) -> None

Store a successful verification result.

Only successful verifications should be cached. Failures (inactive tokens, missing scopes, HTTP errors, timeouts) must not be cached so that transient problems do not produce sticky false negatives.