AuthKit 🤝 FastMCP

Secure your FastMCP server with AuthKit by WorkOS

This guide shows you how to secure your FastMCP server using WorkOS’s AuthKit, a complete authentication and user management solution. This integration uses the Remote OAuth pattern with RFC 8707 resource indicators: AuthKit issues tokens whose aud claim is bound to your server’s resource URL, and FastMCP validates that claim automatically.

Configuration

Prerequisites

Before you begin, you will need:

1. A WorkOS Account and a new Project.
2. An AuthKit instance configured within your WorkOS project.
3. Your FastMCP server’s URL (can be localhost for development, e.g., http://127.0.0.1:8000).

Step 1: WorkOS Dashboard

In the WorkOS Dashboard, go to Connect → Configuration and configure:

1. MCP Auth

   Enable Dynamic Client Registration (DCR) so MCP clients can register themselves. Alternatively, enable Client ID Metadata Document (CIMD) if your clients support it.

2. MCP resource indicators

   Add your FastMCP server’s resource URL (e.g., http://127.0.0.1:8000/mcp) as a valid resource indicator.

   This must exactly match what FastMCP advertises in its protected resource metadata. Start your server first and it will log the correct URL on startup — copy that value.

   Without this step, AuthKit falls back to a default environment-scoped audience and audience validation will fail with a 401.

3. Note Your AuthKit Domain

   Find your AuthKit Domain on the configuration page. It will look like https://your-project-12345.authkit.app. You’ll need this for your FastMCP server configuration.

Step 2: FastMCP Configuration

Create your FastMCP server file and use the AuthKitProvider to handle all the OAuth integration automatically:

server.py

from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import AuthKitProvider

# AuthKitProvider automatically discovers WorkOS endpoints, configures JWT
# validation, and binds the token audience to this server's resource URL.
auth_provider = AuthKitProvider(
    authkit_domain="https://your-project-12345.authkit.app",
    base_url="http://127.0.0.1:8000",  # Use your actual server URL
)

mcp = FastMCP(name="AuthKit Secured App", auth=auth_provider)

When the server starts, it logs the resource URL it is validating against. Paste that URL into your Dashboard’s MCP resource indicators list.

Testing

To test your server, you can use the fastmcp CLI to run it locally. Assuming you’ve saved the above code to server.py (after replacing the authkit_domain and base_url with your actual values!), you can run the following command:

fastmcp run server.py --transport http --port 8000

AuthKit defaults DCR clients to client_secret_basic for token exchange, which conflicts with how some MCP clients send credentials. To avoid token exchange errors, register as a public client by setting token_endpoint_auth_method to "none":

client.py

from fastmcp import Client
from fastmcp.client.auth import OAuth
import asyncio

auth = OAuth(additional_client_metadata={"token_endpoint_auth_method": "none"})

async def main():
    async with Client("http://127.0.0.1:8000/mcp", auth=auth) as client:
        assert await client.ping()

if __name__ == "__main__":
    asyncio.run(main())

Production Configuration

For production deployments, load sensitive configuration from environment variables:

server.py

import os
from fastmcp import FastMCP
from fastmcp.server.auth.providers.workos import AuthKitProvider

# Load configuration from environment variables
auth = AuthKitProvider(
    authkit_domain=os.environ.get("AUTHKIT_DOMAIN"),
    base_url=os.environ.get("BASE_URL", "https://your-server.com"),
)

mcp = FastMCP(name="AuthKit Secured App", auth=auth)