Scalekit 🤝 FastMCP

Secure your FastMCP server with Scalekit

New in version 2.13.0

Install auth stack to your FastMCP server with Scalekit using the Remote OAuth pattern: Scalekit handles user authentication, and the MCP server validates issued tokens.

Prerequisites

Before you begin

1. Get a Scalekit account and grab your Environment URL from Dashboard > Settings .
2. Have your FastMCP server’s base URL ready (can be localhost for development, e.g., http://localhost:8000/)

Step 1: Configure MCP server in Scalekit environment

1. Register MCP server and set environment

   In your Scalekit dashboard:

   1. Open the MCP Servers section, then select Create new server
   2. Enter server details: a name, a resource identifier, and the desired MCP client authentication settings
   3. Save, then copy the Resource ID (for example, res_92015146095)

   In your FastMCP project’s .env:

   SCALEKIT_ENVIRONMENT_URL=<YOUR_APP_ENVIRONMENT_URL>
   SCALEKIT_RESOURCE_ID=<YOUR_APP_RESOURCE_ID> # res_926EXAMPLE5878
   BASE_URL=http://localhost:8000/
   # Optional: additional scopes tokens must have
   # SCALEKIT_REQUIRED_SCOPES=read,write
   

Step 2: Add auth to FastMCP server

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

Warning: The legacy mcp_url and client_id parameters are deprecated and will be removed in a future release. Use base_url instead of mcp_url and remove client_id from your configuration.

server.py

from fastmcp import FastMCP
from fastmcp.server.auth.providers.scalekit import ScalekitProvider

# Discovers Scalekit endpoints and set up JWT token validation
auth_provider = ScalekitProvider(
    environment_url=SCALEKIT_ENVIRONMENT_URL,    # Scalekit environment URL
    resource_id=SCALEKIT_RESOURCE_ID,            # Resource server ID
    base_url=SERVER_URL,                         # Public MCP endpoint
    required_scopes=["read"],                    # Optional scope enforcement
)

# Create FastMCP server with auth
mcp = FastMCP(name="My Scalekit Protected Server", auth=auth_provider)

@mcp.tool
def auth_status() -> dict:
    """Show Scalekit authentication status."""
    # Extract user claims from the JWT
    return {
        "message": "This tool requires authentication via Scalekit",
        "authenticated": True,
        "provider": "Scalekit"
    }

Set required_scopes when you need tokens to carry specific permissions. Leave it unset to allow any token issued for the resource.

Testing

Start the MCP server

uv run python server.py

Use any MCP client (for example, mcp-inspector, Claude, VS Code, or Windsurf) to connect to the running serve. Verify that authentication succeeds and requests are authorized as expected.

Provider selection

Setting this environment variable allows the Scalekit provider to be used automatically without explicitly instantiating it in code.

FASTMCP_SERVER_AUTH · default: "Not set"

Set to fastmcp.server.auth.providers.scalekit.ScalekitProvider to use Scalekit authentication.

Scalekit-specific configuration

These environment variables provide default values for the Scalekit provider, whether it’s instantiated manually or configured via FASTMCP_SERVER_AUTH.

FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL · required

Your Scalekit environment URL from the Admin Portal (e.g., https://your-env.scalekit.com)

FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID · required

Your Scalekit resource server ID from the MCP Servers section

FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_BASE_URL · required

Public URL of your FastMCP server (e.g., https://your-server.com or http://localhost:8000/ for development)

Legacy FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL is still recognized for backward compatibility but will be removed soon-rename it to ...BASE_URL.

FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_REQUIRED_SCOPES · default: "[]"

Comma-, space-, or JSON-separated list of scopes that tokens must include to access your server

Example .env:

# Use the Scalekit provider
FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.scalekit.ScalekitProvider

# Scalekit configuration
FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_ENVIRONMENT_URL=https://your-env.scalekit.com
FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_RESOURCE_ID=res_456
FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_BASE_URL=https://your-server.com/
# FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_REQUIRED_SCOPES=read,write
# FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_MCP_URL=https://your-server.com/  # Deprecated

With environment variables set, your server code simplifies to:

server.py

from fastmcp import FastMCP

# Authentication is automatically configured from environment
mcp = FastMCP(name="My Scalekit Protected Server")

@mcp.tool
def protected_action() -> str:
    """A tool that requires authentication."""
    return "Access granted via Scalekit!"

Capabilities

Scalekit supports OAuth 2.1 with Dynamic Client Registration for MCP clients and enterprise SSO, and provides built‑in JWT validation and security controls.

OAuth 2.1/DCR: clients self‑register, use PKCE, and work with the Remote OAuth pattern without pre‑provisioned credentials.

Validation and SSO: tokens are verified (keys, RS256, issuer, audience, expiry), and SAML, OIDC, OAuth 2.0, ADFS, Azure AD, and Google Workspace are supported; use HTTPS in production and review auth logs as needed.

Debugging

Enable detailed logging to troubleshoot authentication issues:

import logging
logging.basicConfig(level=logging.DEBUG)

Token inspection

You can inspect JWT tokens in your tools to understand the user context:

from fastmcp.server.context import request_ctx
import jwt

@mcp.tool
def inspect_token() -> dict:
    """Inspect the current JWT token claims."""
    context = request_ctx.get()

    # Extract token from Authorization header
    if hasattr(context, 'request') and hasattr(context.request, 'headers'):
        auth_header = context.request.headers.get('authorization', '')
        if auth_header.startswith('Bearer '):
            token = auth_header[7:]
            # Decode without verification (already verified by provider)
            claims = jwt.decode(token, options={"verify_signature": False})
            return claims

    return {"error": "No token found"}