Multiple Auth Sources

Production servers often need to accept tokens from multiple authentication sources. An interactive application might authenticate through an OAuth proxy, while a backend service sends machine-to-machine JWT tokens directly. MultiAuth composes these sources into a single auth provider so every valid token is accepted regardless of where it was issued.

Understanding MultiAuth

MultiAuth wraps an optional auth server (like OAuthProxy) together with one or more token verifiers (like JWTVerifier). When a request arrives with a bearer token, MultiAuth tries each source in order and accepts the first successful verification. The auth server, if provided, is tried first. It owns all OAuth routes and metadata — the verifiers contribute only token verification logic. This keeps the MCP discovery surface clean: one set of routes, one set of metadata, multiple verification paths.

from fastmcp import FastMCP
from fastmcp.server.auth import MultiAuth, OAuthProxy
from fastmcp.server.auth.providers.jwt import JWTVerifier

upstream_verifier = JWTVerifier(
    jwks_uri="https://login.example.com/.well-known/jwks.json",
    issuer="https://login.example.com",
    audience="my-app",
)

auth = MultiAuth(
    server=OAuthProxy(
        upstream_authorization_endpoint="https://login.example.com/oauth/authorize",
        upstream_token_endpoint="https://login.example.com/oauth/token",
        upstream_client_id="my-app",
        upstream_client_secret="secret",
        token_verifier=upstream_verifier,
        base_url="https://my-server.com",
    ),
    verifiers=[
        JWTVerifier(
            jwks_uri="https://internal-issuer.example.com/.well-known/jwks.json",
            issuer="https://internal-issuer.example.com",
            audience="my-mcp-server",
        ),
    ],
)

mcp = FastMCP("My Server", auth=auth)

Interactive MCP clients authenticate through the OAuth proxy as usual. Backend services skip OAuth entirely and send a JWT signed by the internal issuer. Both paths are validated, and the first match wins.

Verification Order

MultiAuth checks sources in a deterministic order:

Server (if provided) — the full auth provider’s verify_token runs first
Verifiers — each TokenVerifier is tried in mapping or list order

The first source that returns a valid AccessToken wins. If every source returns None, the request receives a 401 response. This ordering means the server acts as the “primary” authentication path, with verifiers as fallbacks for tokens the server doesn’t recognize.

Verifiers Only

You don’t always need a full OAuth server. If your server only needs to accept tokens from multiple issuers, pass verifiers without a server:

from fastmcp import FastMCP
from fastmcp.server.auth import MultiAuth
from fastmcp.server.auth.providers.jwt import JWTVerifier, StaticTokenVerifier

auth = MultiAuth(
    verifiers=[
        JWTVerifier(
            jwks_uri="https://issuer-a.example.com/.well-known/jwks.json",
            issuer="https://issuer-a.example.com",
            audience="my-server",
        ),
        JWTVerifier(
            jwks_uri="https://issuer-b.example.com/.well-known/jwks.json",
            issuer="https://issuer-b.example.com",
            audience="my-server",
        ),
    ],
)

mcp = FastMCP("Multi-Issuer Server", auth=auth)

Without a server, no OAuth routes or metadata are served. This is appropriate for internal systems where clients already know how to obtain tokens.

Challenge Scopes

Clients use the WWW-Authenticate challenge to decide which scopes to request. When you omit required_scopes or pass None, MultiAuth delegates default challenge selection to its server, or to its sole verifier when no server is configured. This preserves custom get_challenge_scopes(None) hooks. With multiple verifiers and no server, it does not select or combine their defaults; no scope parameter is advertised unless you configure required_scopes. An explicit required_scopes list is passed to the delegated challenge hook and also sets the scopes required by MultiAuth’s HTTP middleware. An empty list removes that outer scope requirement. Each verifier still enforces its own token validation requirements, so required_scopes=[] does not make invalid or under-scoped tokens valid. When the server is a RemoteAuthProvider, its configured challenge_scopes applies when the effective scopes equal that provider’s required_scopes, including an explicit list with the same values. A different explicit list is passed to the verifier’s hook for translation. Without configured challenge_scopes, the verifier receives the supplied list, or None to select its default.

Source Names

Each source has a stable identity for sessions, background tasks, and continued requests. Use an ordered mapping to give verifiers explicit names; pass server_source_id to name the delegated auth server. These names follow the source across restarts and changes to verification order. MultiAuth qualifies the returned token’s client_id with this source identity and the verified issuer and subject, when present. Its original_client_id field contains the identifier returned by the verifier; bearer token bytes, claims, subject, and scopes stay the same.

from fastmcp.server.auth import MultiAuth
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier

company = StaticTokenVerifier(tokens={"company-token": {"client_id": "service", "scopes": []}})
partner = StaticTokenVerifier(tokens={"partner-token": {"client_id": "service", "scopes": []}})
auth = MultiAuth(verifiers={"company": company, "partner": partner})

List and single-verifier forms remain available when their derived source identities are distinct. JWT verifiers derive identities from configured issuers and JWKS URLs; introspection verifiers use their endpoint, remote providers use their wrapped verifier, OAuth proxies use their configured issuer, upstream endpoints, and verifier, other OAuth servers use their configured issuer, and other providers use their Python type. Explicit names are recommended when configuration or provider types may change.

This changes get_access_token().client_id and ownership for existing MultiAuth sessions, tasks, and continued requests. Update authorization checks that compare the verifier’s original client ID to read get_access_token().original_client_id instead. Recreate sessions and resubmit tasks after upgrading. Configurations with duplicate derived identities now need explicit names, including multiple static verifiers or custom verifiers of the same type. Changing a source name starts a new ownership scope.

API Reference

MultiAuth

Parameter	Type	Description
`server`	`AuthProvider \| None`	Optional auth provider that owns routes and OAuth metadata. Also tried first for token verification.
`verifiers`	`Mapping[str, TokenVerifier] \| list[TokenVerifier] \| TokenVerifier`	Named or distinctly configured token verifiers tried after the server.
`server_source_id`	`str \| None`	Stable name for the delegated server source. Defaults to its derived identity.
`base_url`	`str \| None`	Override the base URL. Defaults to the server’s `base_url`.
`required_scopes`	`list[str] \| None`	Override required scopes. Defaults to the server’s scopes.

Get Started

Servers

Apps

Clients

Integrations

More

Multiple Auth Sources

Understanding MultiAuth

Verification Order

Verifiers Only

Challenge Scopes

Source Names

API Reference

MultiAuth

​Understanding MultiAuth

​Verification Order

​Verifiers Only

​Challenge Scopes

​Source Names

​API Reference

​MultiAuth

Understanding MultiAuth

Verification Order

Verifiers Only

Challenge Scopes

Source Names

API Reference

MultiAuth