docs/v2/integrations/workos.mdx
import { VersionBadge } from "/snippets/version-badge.mdx"
<VersionBadge version="2.12.0" />Secure your FastMCP server with WorkOS Connect authentication. This integration uses the OAuth Proxy pattern to handle authentication through WorkOS Connect while maintaining compatibility with MCP clients.
<Note> This guide covers WorkOS Connect applications. For Dynamic Client Registration (DCR) with AuthKit, see the [AuthKit integration](/v2/integrations/authkit) instead. </Note>Before you begin, you will need:
http://localhost:8000)Create an OAuth App in your WorkOS dashboard to get the credentials needed for authentication:
<Steps> <Step title="Create OAuth Application"> In your WorkOS dashboard: 1. Navigate to **Applications** 2. Click **Create Application** 3. Select **OAuth Application** 4. Name your application </Step> <Step title="Get Credentials"> In your OAuth application settings: 1. Copy your **Client ID** (starts with `client_`) 2. Click **Generate Client Secret** and save it securely 3. Copy your **AuthKit Domain** (e.g., `https://your-app.authkit.app`) </Step> <Step title="Configure Redirect URI"> In the **Redirect URIs** section: - Add: `http://localhost:8000/auth/callback` (for development) - For production, add your server's public URL + `/auth/callback` <Warning> The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. </Warning> </Step> </Steps>Create your FastMCP server using the WorkOSProvider:
from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import WorkOSProvider
# Configure WorkOS OAuth
auth = WorkOSProvider(
client_id="client_YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
authkit_domain="https://your-app.authkit.app",
base_url="http://localhost:8000",
required_scopes=["openid", "profile", "email"]
)
mcp = FastMCP("WorkOS Protected Server", auth=auth)
@mcp.tool
def protected_tool(message: str) -> str:
"""This tool requires authentication."""
return f"Authenticated user says: {message}"
if __name__ == "__main__":
mcp.run(transport="http", port=8000)
Start your FastMCP server with HTTP transport to enable OAuth flows:
fastmcp run server.py --transport http --port 8000
Your server is now running and protected by WorkOS OAuth authentication.
Create a test client that authenticates with your WorkOS-protected server:
from fastmcp import Client
import asyncio
async def main():
# The client will automatically handle WorkOS OAuth
async with Client("http://localhost:8000/mcp", auth="oauth") as client:
# First-time connection will open WorkOS login in your browser
print("✓ Authenticated with WorkOS!")
# Test the protected tool
result = await client.call_tool("protected_tool", {"message": "Hello!"})
print(result)
if __name__ == "__main__":
asyncio.run(main())
When you run the client for the first time:
For production deployments with persistent token management across server restarts, configure jwt_signing_key, and client_storage:
import os
from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import WorkOSProvider
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet
# Production setup with encrypted persistent token storage
auth = WorkOSProvider(
client_id="client_YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
authkit_domain="https://your-app.authkit.app",
base_url="https://your-production-domain.com",
required_scopes=["openid", "profile", "email"],
# Production token management
jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
client_storage=FernetEncryptionWrapper(
key_value=RedisStore(
host=os.environ["REDIS_HOST"],
port=int(os.environ["REDIS_PORT"])
),
fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
)
)
mcp = FastMCP(name="Production WorkOS App", auth=auth)
For complete details on these parameters, see the OAuth Proxy documentation. </Note>
For production deployments, use environment variables instead of hardcoding credentials.
Setting this environment variable allows the WorkOS provider to be used automatically without explicitly instantiating it in code.
<Card> <ParamField path="FASTMCP_SERVER_AUTH" default="Not set"> Set to `fastmcp.server.auth.providers.workos.WorkOSProvider` to use WorkOS authentication. </ParamField> </Card>These environment variables provide default values for the WorkOS provider, whether it's instantiated manually or configured via FASTMCP_SERVER_AUTH.
Example .env file:
# WorkOS OAuth credentials (always used as defaults)
FASTMCP_SERVER_AUTH_WORKOS_CLIENT_ID=client_01K33Y6GGS7T3AWMPJWKW42Y3Q
FASTMCP_SERVER_AUTH_WORKOS_CLIENT_SECRET=your_client_secret
FASTMCP_SERVER_AUTH_WORKOS_AUTHKIT_DOMAIN=https://your-app.authkit.app
FASTMCP_SERVER_AUTH_WORKOS_BASE_URL=https://your-server.com
FASTMCP_SERVER_AUTH_WORKOS_REQUIRED_SCOPES=["openid","profile","email"]
# Optional: Automatically provision WorkOS auth for all servers
FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.WorkOSProvider
With environment variables set, you can either:
Option 1: Manual instantiation (env vars provide defaults)
from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import WorkOSProvider
# Env vars provide default values for WorkOSProvider()
auth = WorkOSProvider() # Uses env var defaults
mcp = FastMCP(name="WorkOS Protected Server", auth=auth)
Option 2: Automatic provisioning (requires FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.WorkOSProvider)
from fastmcp import FastMCP
# Auth is automatically provisioned from FASTMCP_SERVER_AUTH
mcp = FastMCP(name="WorkOS Protected Server")