Skip to main content

​
fastmcp.server.auth.providers.clerk

Clerk OAuth provider for FastMCP. This module provides a complete Clerk OAuth integration that’s ready to use with a Clerk domain, client ID, and client secret. It handles all the complexity of Clerk’s OAuth/OIDC flow, token validation, and user management. Clerk uses standard OIDC endpoints derived from the instance domain (e.g., https://<instance>.clerk.accounts.dev). Token verification is performed via the introspection endpoint (RFC 7662) for security-critical checks (active status, audience, scopes), followed by the userinfo endpoint for profile enrichment. Userinfo failure is non-fatal. Example: 
from fastmcp import FastMCP
from fastmcp.server.auth.providers.clerk import ClerkProvider

auth = ClerkProvider(
    domain="saving-primate-16.clerk.accounts.dev",
    client_id="your-clerk-client-id",
    client_secret="your-clerk-client-secret",
    base_url="https://my-server.com",
)

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

​
Classes

​
ClerkTokenVerifier

Token verifier for Clerk OAuth tokens. Clerk issues standard OIDC tokens. Verification uses the introspection endpoint (RFC 7662) as the primary security gate — it confirms the token is active and provides metadata (scopes, expiry, audience). The userinfo endpoint is called second for profile enrichment (name, email, picture) and its failure is non-fatal. When a client_id is configured, the audience from introspection is validated against it. When required_scopes are configured, introspection must return the token’s scopes — the verifier will not assume scopes when introspection is unavailable. Methods:

​
verify_token 

verify_token(self, token: str) -> AccessToken | None
Verify a Clerk OAuth token via introspection and userinfo. Calls the introspection endpoint first to validate the token and retrieve auth metadata (active status, scopes, expiry, audience). If the token passes security checks, the userinfo endpoint is called for profile enrichment. Userinfo failure is non-fatal. When a client_id is configured, the token’s audience must match it. When required_scopes are configured, introspection must confirm them; tokens are rejected if scope information is unavailable.

​
ClerkProvider

Complete Clerk OAuth provider for FastMCP. This provider makes it trivial to add Clerk OAuth protection to any FastMCP server. Provide your Clerk instance domain, OAuth app credentials, and a base URL, and you’re ready to go. Clerk uses standard OIDC endpoints derived from the instance domain. All endpoint URLs are constructed automatically from the domain parameter. Features:
  • Transparent OAuth proxy to Clerk
  • Automatic token validation via Clerk’s userinfo & introspection APIs
  • User information extraction from Clerk’s OIDC claims
  • PKCE support (S256)
  • Minimal configuration required