mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 15:19:10 +02:00
85b7efd746Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>
94 lines
3.5 KiB
Text
94 lines
3.5 KiB
Text
---
|
|
title: clerk
|
|
sidebarTitle: clerk
|
|
---
|
|
|
|
# `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:
|
|
```python
|
|
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` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/clerk.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
|
|
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` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/clerk.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
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` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/clerk.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
|
|
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
|
|
|