FastMCP OAuth Server

# 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 ```bash # 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](https://manage.auth0.com/) → 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: ```bash # 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 ```bash 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:** ```bash uv run python -m client # Or: uv run python client/cli.py ``` **Run Demos:** ```bash # 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 ```bash # Install MCP Inspector npm install -g @modelcontextprotocol/inspector # Test the server npx @modelcontextprotocol/inspector http://localhost:8000/mcp ``` ### Testing with cURL ```bash # 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 ```bash # Install development dependencies uv sync --extra dev # Run tests (when implemented) uv run pytest tests/ ``` ### Code Formatting ```bash # 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: ```python # 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: ```bash 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](https://github.com/jlowin/fastmcp) - Review [Auth0 documentation](https://auth0.com/docs)