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
- 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
- Configure Callback URLs:
http://localhost:8000/auth0/callback
- Configure Logout URLs:
- 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
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 validationMCPConfig: MCP server configurationAppConfig: Combined application configurationload_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 classAuth0Error: Auth0-specific errorsTokenValidationError: Token-related errorsAuthorizationError: Authorization failures
app.py - Main Application
create_oauth_provider(): OAuth provider factorycreate_mcp_server(): MCP server with toolscreate_app(): FastAPI application setup- Route handlers and middleware configuration
API Endpoints
OAuth Endpoints
GET /.well-known/oauth-authorization-server - OAuth discoveryGET /auth0/callback - Auth0 callback handler
MCP Endpoints
POST /mcp - MCP protocol endpoint (requires authentication)
Utility Endpoints
GET /health - Health checkGET /debug/auth0 - Auth0 configuration debug (development only)
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/
# Format code
uv run black .
# Sort imports
uv run isort .
# Lint with ruff
uv run ruff check .
uv run ruff format .
Production Considerations
Security
- Environment Variables: Never commit
.env files - CORS Configuration: Restrict
allow_origins in production - Token Storage: Replace in-memory storage with Redis/database
- HTTPS: Always use HTTPS in production
- Secrets Management: Use proper secret management systems
Scaling
- Database: Replace in-memory storage with persistent storage
- Caching: Add Redis for token caching
- Load Balancing: Configure for multiple instances
- 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
- Auth0 Configuration Errors
- Verify callback URLs match exactly
- Check Auth0 domain format (no
https://) - Ensure client secret is correct
- Token Validation Failures
- Check token expiration
- Verify required scopes are granted
- Ensure proper audience configuration
- 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: