FastMCP OAuth Server with Auth0

A modular FastMCP server implementation with Auth0 OAuth 2.0 authentication

Features

• 🔐 OAuth 2.0 Authentication with Auth0
• 🛠️ FastMCP Integration for AI tool serving
• 🔍 Debugging Support with health checks
• 📊 Structured Logging throughout the application

Project Structure

mcp-oauth/
├── server/              # FastMCP server (OAuth-secured)
│   ├── app.py          # Main server application
│   ├── oauth.py        # Auth0 OAuth provider
│   ├── config.py       # Configuration management
│   └── exceptions.py   # Custom exceptions
├── client/              # MCP client (OAuth-enabled)
│   ├── client.py       # Main client implementation
│   ├── auth_handler.py # OAuth authentication handler
│   └── cli.py         # Command-line interface
├── demos/               # Usage demonstrations
│   ├── basic_demo.py   # Complete OAuth flow demo
│   └── weather_demo.py # Weather tool demo
├── pyproject.toml       # Project configuration and dependencies
├── .env                # Environment variables (create from template below)
└── README.md           # This file

Quick Start

1. Install Dependencies

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

# Install dependencies
uv sync

2. Configure Auth0

1. Create Auth0 Application:

   • Go to Auth0 Dashboard → Applications
   • Click "Create Application"
   • Create a Name and choose "Regular Web Application"
   • Add http://localhost:8080/callback to the Allowed Callback URL's on Settings tab
   • Note down: Domain, Client ID, Client Secret from your Settings tab

2. Configure Callback URLs:

   http://localhost:8000/auth0/callback
   

3. Configure Logout URLs:

   http://localhost:8000
   

4. Create API (Optional):

   • Go to APIs → Create API
   • Set identifier (e.g., https://mcp-server.example.com)
   • This becomes your AUTH0_AUDIENCE

3. Environment Variables

Create a .env file in the project root using .env.example as a template:

# Auth0 Configuration (Required)
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your_auth0_client_id_here
AUTH0_CLIENT_SECRET=your_auth0_client_secret_here
AUTH0_AUDIENCE=your_api_identifier_here

# MCP Server Configuration
MCP_HOST=localhost
MCP_PORT=8000
MCP_DEBUG=false
MCP_ISSUER_URL=http://localhost:8000

# OAuth Scopes Configuration
DEFAULT_SCOPES=openid profile email
REQUIRED_SCOPES=read:mcp write:mcp

# Security Settings
TOKEN_EXPIRY_SECONDS=3600
ENABLE_CLIENT_REGISTRATION=true

4. Run the Server

uv run python -m server

The server will start on http://localhost:8000

curl http://localhost:8000/health

5. Test with the Client

Interactive CLI:

uv run python -m client
# Or: uv run python client/cli.py

Run Demos:

# Basic OAuth flow demo
uv run python -m demos
# Or: uv run python demos/basic_demo.py

# Weather tool demo
uv run python demos/weather_demo.py

Architecture Overview

Modular Design

This project demonstrates clean separation of concerns:

config.py - Configuration Management

• Auth0Config: Auth0-specific settings with validation
• MCPConfig: MCP server configuration
• AppConfig: Combined application configuration
• load_config(): Environment variable loading with defaults

oauth.py - OAuth Provider

• Auth0OAuthProvider: Complete OAuth 2.0 implementation
• Handles authorization flows, token exchange, and validation
• Integrates with Auth0 APIs
• Manages client registration and scopes

exceptions.py - Error Handling

• MCPOAuthError: Base exception class
• Auth0Error: Auth0-specific errors
• TokenValidationError: Token-related errors
• AuthorizationError: Authorization failures

app.py - Main Application

• create_oauth_provider(): OAuth provider factory
• create_mcp_server(): MCP server with tools
• create_app(): FastAPI application setup
• Route handlers and middleware configuration

API Endpoints

OAuth Endpoints

• GET /.well-known/oauth-authorization-server - OAuth discovery
• GET /auth0/callback - Auth0 callback handler

MCP Endpoints

• POST /mcp - MCP protocol endpoint (requires authentication)

Utility Endpoints

• GET /health - Health check
• GET /debug/auth0 - Auth0 configuration debug (development only)

MCP Tools

The server includes example tools that require authentication:

get_weather(city: str)

Mock weather data for a given city.

get_user_info()

Returns current authenticated user information.

protected_action(action: str)

Demonstrates a protected action requiring authentication.

Usage Examples

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test the server
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

Testing with cURL

# Health check
curl http://localhost:8000/health

# Debug Auth0 configuration
curl http://localhost:8000/debug/auth0

# OAuth discovery
curl http://localhost:8000/.well-known/oauth-authorization-server

Development

Code Quality

The project follows Python best practices:

• Type hints throughout the codebase
• Docstrings for all classes and functions
• Structured logging with appropriate levels
• Error handling with custom exceptions
• Configuration validation with clear error messages

Testing

# Install development dependencies
uv sync --extra dev

# Run tests (when implemented)
uv run pytest tests/

Code Formatting

# Format code
uv run black .

# Sort imports
uv run isort .

# Lint with ruff
uv run ruff check .
uv run ruff format .

Production Considerations

Security

1. Environment Variables: Never commit .env files
2. CORS Configuration: Restrict allow_origins in production
3. Token Storage: Replace in-memory storage with Redis/database
4. HTTPS: Always use HTTPS in production
5. Secrets Management: Use proper secret management systems

Scaling

1. Database: Replace in-memory storage with persistent storage
2. Caching: Add Redis for token caching
3. Load Balancing: Configure for multiple instances
4. Monitoring: Add application monitoring and metrics

Configuration

Update the following for production:

# In app.py - CORS configuration
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],  # Restrict origins
    allow_credentials=True,
    allow_methods=["GET", "POST"],  # Restrict methods
    allow_headers=["Authorization", "Content-Type"],  # Restrict headers
)

Troubleshooting

Common Issues

1. Auth0 Configuration Errors

   • Verify callback URLs match exactly
   • Check Auth0 domain format (no https://)
   • Ensure client secret is correct

2. Token Validation Failures

   • Check token expiration
   • Verify required scopes are granted
   • Ensure proper audience configuration

3. CORS Issues

   • Update CORS configuration for your client domain
   • Check preflight request handling

Debug Mode

Enable debug mode for detailed logging:

MCP_DEBUG=true uv run python -m server

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the FastMCP documentation
• Review Auth0 documentation