FastMCP Server with Scalekit OAuth Example

This example demonstrates how to build an MCP server using the FastMCP framework with Scalekit as the OAuth provider for authentication and authorization.

Features

• OAuth 2.1 Authentication: Uses Scalekit for secure user authentication
• Dynamic Client Registration: Supports DCR for automated client setup
• JWT Token Validation: Validates access tokens from Scalekit
• Scope-based Authorization: Fine-grained access control for different operations
• Resource Discovery: Provides OAuth resource metadata endpoint

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment Variables

Copy the example environment file and fill in your Scalekit details:

cp .env.example .env

Edit .env with your Scalekit configuration:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=your_client_id_from_scalekit
SCALEKIT_CLIENT_SECRET=your_client_secret_from_scalekit
SCALEKIT_RESOURCE_ID=your_resource_id_from_scalekit
SERVER_BASE_URL=https://your-server-domain.com

3. Scalekit Setup

1. Create a Scalekit Account: Sign up at Scalekit

2. Register Your MCP Server:

   • Go to your Scalekit dashboard
   • Create a new application
   • Note down your Client ID and Client Secret

3. Register MCP Server Resource:

   • In your Scalekit dashboard, navigate to "Resources" or "MCP Servers"
   • Click "Register New MCP Server" or "Add Resource"
   • Fill in your MCP server details:
     • Name: Your MCP server name (e.g., "My FastMCP Server")
     • Base URL: Your server's base URL (e.g., http://localhost:8000/mcp)
     • Description: Brief description of your server's functionality
   • After registration, copy the Resource ID from the dashboard
   • This Resource ID should be used as SCALEKIT_RESOURCE_ID in your .env file

4. Configure Scopes: Set up the required scopes in your Scalekit application:

   • profile:read
   • organizations:read
   • resources:read
   • resources:write
   • metrics:read

Running the Server

Method 1: Direct Execution

python server.py

Method 2: Using FastMCP CLI

fastmcp run server.py:mcp

Available Tools

The server provides the following authenticated tools:

• get_user_profile(user_id): Get user profile information
• list_organizations(): List accessible organizations (requires organizations:read scope)
• create_resource(name, description, organization_id): Create resources (requires resources:write scope)
• get_api_metrics(): Get API usage metrics (requires metrics:read scope)

OAuth Flow

1. Client Registration: MCP clients can use Scalekit's Dynamic Client Registration
2. Authorization: Users authenticate via Scalekit's OAuth flow
3. Token Issuance: Scalekit issues JWT access tokens with appropriate scopes
4. API Access: Clients include tokens in requests to the MCP server
5. Token Validation: Server validates tokens using Scalekit's JWKS endpoint

Security Features

• JWT Validation: All tokens are validated against Scalekit's JWKS
• Scope Enforcement: Tools can check for required scopes
• Audience Validation: Ensures tokens are intended for this server
• Expiration Checking: Automatically rejects expired tokens

Development

Testing with curl

# Get an access token from Scalekit first, then:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -X POST \
     -d '{"method": "tools/call", "params": {"name": "list_organizations", "arguments": {}}}' \
     http://localhost:8000

Adding New Tools

@mcp.tool
def your_new_tool(param: str) -> dict:
    """Your tool description"""
    # Add scope checking if needed
    # Implement your business logic
    return {"result": "success"}

Production Considerations

• Use HTTPS in production
• Set appropriate CORS policies
• Implement rate limiting
• Add comprehensive logging
• Use environment-specific Scalekit configurations
• Consider token caching strategies for performance

Resources

• FastMCP Documentation
• Scalekit OAuth Guide
• MCP Specification