Provides OAuth 2.0 authentication for the MCP server, handling authorization flows, token exchange, and validation to secure MCP endpoints
Manages environment variables and configuration for the MCP server, including Auth0 credentials and server settings
Suggested as a production enhancement for token caching and to replace in-memory storage for better scaling
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
Quick Start
1. Install Dependencies
2. Configure Auth0
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 tabNote down: Domain, Client ID, Client Secret from your Settings tab
Configure Callback URLs:
http://localhost:8000/auth0/callbackConfigure Logout URLs:
http://localhost:8000Create 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:
4. Run the Server
The server will start on http://localhost:8000
5. Test with the Client
Interactive CLI:
Run Demos:
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 implementationHandles 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 setupRoute 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)
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
Testing with cURL
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
Code Formatting
Production Considerations
Security
Environment Variables: Never commit
.env
filesCORS Configuration: Restrict
allow_origins
in productionToken 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:
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:
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
Check the FastMCP documentation
Review Auth0 documentation
This server cannot be installed
A modular server implementation that integrates Auth0 OAuth 2.0 authentication with FastMCP to securely serve AI tools through the Model Context Protocol.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server implementation that enables connection between OpenAI APIs and MCP clients for coding assistance with features like CLI interaction, web API integration, and tool-based architecture.Last updated -34
- AsecurityFlicenseAqualityA server that enables AI to access external services through the Model Context Protocol, specifically integrating with an authentication system to obtain login tickets.
- -securityFlicense-qualityA Model Context Protocol server that requires user authentication via Auth0 before enabling secure API access on behalf of the authenticated user.Last updated -
- -securityAlicense-qualityA comprehensive Model Context Protocol server template that implements HTTP-based transport with OAuth proxy for third-party authorization servers like Auth0, enabling AI tools to securely connect while supporting Dynamic Application Registration.Last updated -75MIT License