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

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:
http://localhost:8000
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

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:

Check the FastMCP documentation
Review Auth0 documentation

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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

OpenAI MCP Server
arthurcolle
-
security
F
license
-
quality
A 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 -
35
MCP-ALBERTO
A
security
F
license
A
quality
A server that enables AI to access external services through the Model Context Protocol, specifically integrating with an authentication system to obtain login tickets.
Auth0 OAuth MCP Server
pratham-svg
-
security
F
license
-
quality
A Model Context Protocol server that requires user authentication via Auth0 before enabling secure API access on behalf of the authenticated user.
Last updated -
MCP Server Boilerplate
chrisleekr
-
security
A
license
-
quality
A 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 -
9
5
MIT License

View all related MCP servers