fastmcp.server.auth.providers.workos

WorkOS authentication providers for FastMCP.

This module provides two WorkOS authentication strategies:

1. WorkOSProvider - OAuth proxy for WorkOS Connect applications (non-DCR)
2. AuthKitProvider - DCR-compliant provider for WorkOS AuthKit

Choose based on your WorkOS setup and authentication requirements.

Classes

WorkOSTokenVerifier ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Token verifier for WorkOS OAuth tokens.

WorkOS AuthKit tokens are opaque, so we verify them by calling the /oauth2/userinfo endpoint to check validity and get user info.

Methods:

verify_token ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

verify_token(self, token: str) -> AccessToken | None

Verify WorkOS OAuth token by calling userinfo endpoint.

WorkOSProvider ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Complete WorkOS OAuth provider for FastMCP.

This provider implements WorkOS AuthKit OAuth using the OAuth Proxy pattern. It provides OAuth2 authentication for users through WorkOS Connect applications.

Features:

• Transparent OAuth proxy to WorkOS AuthKit
• Automatic token validation via userinfo endpoint
• User information extraction from ID tokens
• Support for standard OAuth scopes (openid, profile, email)

Setup Requirements:

1. Create a WorkOS Connect application in your dashboard
2. Note your AuthKit domain (e.g., "https://your-app.authkit.app")
3. Configure redirect URI as: http://localhost:8000/auth/callback
4. Note your Client ID and Client Secret

AuthKitProvider ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

AuthKit metadata provider for DCR (Dynamic Client Registration).

This provider implements AuthKit integration using metadata forwarding instead of OAuth proxying. This is the recommended approach for WorkOS DCR as it allows WorkOS to handle the OAuth flow directly while FastMCP acts as a resource server.

IMPORTANT SETUP REQUIREMENTS:

1. Enable Dynamic Client Registration in WorkOS Dashboard:

   • Go to Applications → Configuration
   • Toggle "Dynamic Client Registration" to enabled

2. Configure your FastMCP server URL as a callback:

   • Add your server URL to the Redirects tab in WorkOS dashboard
   • Example: https://your-fastmcp-server.com/oauth2/callback

For detailed setup instructions, see: https://workos.com/docs/authkit/mcp/integrating/token-verification

Token audience is bound to this server automatically: when the MCP mount path becomes known (typically at http_app() construction), JWTVerifier.audience is set to the resource URL advertised in .well-known/oauth-protected-resource. Enable Resource Indicators (RFC 8707) in your WorkOS Dashboard and list that same URL — AuthKit will then mint tokens with the matching aud claim.

Methods:

set_mcp_path ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_mcp_path(self, mcp_path: str | None) -> None

Bind the default verifier's audience to this server's resource URL.

AuthKit with Resource Indicators (RFC 8707) mints tokens whose aud claim equals the resource URL the client requested — which is the URL we advertise in .well-known/oauth-protected-resource. Binding the audience here keeps validation in lock-step with what clients are sent.

get_routes ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_routes(self, mcp_path: str | None = None) -> list[Route]

Get OAuth routes including AuthKit authorization server metadata forwarding.

This returns the standard protected resource routes plus an authorization server metadata endpoint that forwards AuthKit's OAuth metadata to clients.

Args:

• mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp") This is used to advertise the resource URL in metadata.