PrefectHQ/fastmcp · error · TypeError

Expected fastmcp.server.auth.auth.AccessToken, got {type(acc

Error message

Expected fastmcp.server.auth.auth.AccessToken, got {type(access_token).__name__}. Ensure the SDK is using the correct AccessToken type.

What it means

get_access_token() converts the access token found in the request context into fastmcp's own AccessToken type. This TypeError is thrown when conversion fails because the object in context is not the expected AccessToken shape — typically an AccessToken class imported from the mcp SDK rather than fastmcp.server.auth.auth, whose constructor fields differ. The message explicitly tells you which type was found.

Source

Thrown at fastmcp_slim/fastmcp/server/dependencies.py:655

    # If the object is not a FastMCP AccessToken, convert it to one if the
    # fields are compatible (e.g. `claims` is not present in the SDK's AccessToken).
    # This is a workaround for the case where the SDK or auth provider returns a different type
    # If it fails, it will raise a TypeError
    try:
        access_token_as_dict = access_token.model_dump()
        return AccessToken(
            token=access_token_as_dict["token"],
            client_id=access_token_as_dict["client_id"],
            scopes=access_token_as_dict["scopes"],
            # Optional fields
            expires_at=access_token_as_dict.get("expires_at"),
            resource=access_token_as_dict.get("resource"),
            subject=access_token_as_dict.get("subject"),
            claims=access_token_as_dict.get("claims") or {},
        )
    except Exception as e:
        raise TypeError(
            f"Expected fastmcp.server.auth.auth.AccessToken, got {type(access_token).__name__}. "
            "Ensure the SDK is using the correct AccessToken type."
        ) from e


# --- Schema generation helper ---


@lru_cache(maxsize=5000)
def without_injected_parameters(
    fn: Callable[..., Any], *, run_in_thread: bool = True
) -> Callable[..., Any]:
    """Create a wrapper function without injected parameters.

    Returns a wrapper that excludes Context and Docket dependency parameters,
    making it safe to use with Pydantic TypeAdapter for schema generation and
    validation. The wrapper internally handles all dependency resolution and
    Context injection when called.

View on GitHub (pinned to 1f02114297)

Solutions

1. Construct fastmcp.server.auth.auth.AccessToken (token, client_id, expires_at, resource, subject, claims) from the SDK token before storing it in context.
2. In custom TokenVerifier implementations, return the FastMCP AccessToken type, not the mcp SDK type.
3. Update the auth integration so it uses FastMCP's token model; the wrapper is a thin shim around the same fields.

Example fix

// before
from mcp.server.auth.types import AccessToken
return AccessToken(token=raw, client_id="x")
// after
from fastmcp.server.auth.auth import AccessToken
return AccessToken(token=raw, client_id="x", scopes=[], expires_at=None, resource=None, subject=None, claims={})

from fastmcp.server.auth.auth import AccessToken
assert isinstance(token, AccessToken), f"wrong token type: {type(token).__name__}"

from fastmcp.server.auth.auth import AccessToken
def is_fastmcp_token(t) -> bool:
    return isinstance(t, AccessToken)

try:
    token = get_access_token()
except TypeError as e:
    if "Expected fastmcp.server.auth.auth.AccessToken" in str(e):
        token = None  # fall back to unauthenticated handling
    else:
        raise

When it happens

Trigger: Calling get_access_token() when middleware/auth code stored an mcp.server.auth.types.AccessToken (or other token type) in the request context instead of fastmcp's AccessToken; custom OAuth proxies passing raw SDK tokens.

Common situations: Copy-pasting OAuth examples from the MCP SDK docs into FastMCP auth providers; upgrading fastmcp where the token type was unified; custom TokenVerifier returning the SDK token type.

Related errors

• OAuth client not found - cached credentials may be stale
• OAuth server rejected the static client credentials. Verify
• Assertion must include exp claim
• Assertion must include sub claim
• Assertion missing required scopes: {sorted(missing)}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/a5e78fd6a8b2b097. Report an issue: GitHub.