> ## Documentation Index

> Fetch the complete documentation index at: /llms.txt

> Use this file to discover all available pages before exploring further.

Skip to main content
Auth

# WorkOS 🤝 FastMCP

Authenticate FastMCP servers with WorkOS Connect

New in 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.
This guide covers WorkOS Connect applications. For Dynamic Client Registration (DCR) with AuthKit, see the AuthKit integration instead.

##
​
Configuration

###
​
Prerequisites

Before you begin, you will need:

1. A WorkOS Account with access to create OAuth Apps
2. Your FastMCP server’s URL (can be localhost for development, e.g., `http://localhost:8000`)

###
​
Step 1: Create a WorkOS OAuth App

Create an OAuth App in your WorkOS dashboard to get the credentials needed for authentication:
1

Create OAuth Application

In your WorkOS dashboard:

1. Navigate to Applications
2. Click Create Application
3. Select OAuth Application
4. Name your application

2

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`)

3

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`

The callback URL must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter.

###
​
Step 2: FastMCP Configuration

Create your FastMCP server using the `WorkOSProvider`:
server.py

    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)

##
​
Testing

###
​
Running the Server

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.

###
​
Testing with a Client

Create a test client that authenticates with your WorkOS-protected server:
client.py

    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:

1. Your browser will open to WorkOS’s authorization page
2. After you authorize the app, you’ll be redirected back
3. The client receives the token and can make authenticated requests

The client caches tokens locally, so you won’t need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.

##
​
Production Configuration

New in version `2.13.0` For production deployments with persistent token management across server restarts, configure `jwt_signing_key`, and `client_storage`:
server.py

    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)

Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.For complete details on these parameters, see the OAuth Proxy documentation.

##
​
Configuration Options

##

​
client_id
required
WorkOS OAuth application client ID
​
client_secret
required
WorkOS OAuth application client secret
​
authkit_domain
required
Your WorkOS AuthKit domain URL (e.g., `https://your-app.authkit.app`)
​
base_url
required
Your FastMCP server’s public URL
​
required_scopes
default:"[]"
OAuth scopes to request
​
redirect_path
default:"/auth/callback"
OAuth callback path
​
timeout_seconds
default:"10"
API request timeout
Supabase 🤝 FastMCP
Previous
FastAPI 🤝 FastMCP
Next
⌘I
Assistant
Responses are generated using AI and may contain mistakes.