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

# 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 -
33
Python
MCP-ALBERTO
feriveragom
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.
Last updated -
1
TypeScript
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 -
TypeScript
google-ads-mcp-server
gomarble-ai
-
security
A
license
-
quality
A FastMCP-powered Model Context Protocol server for Google Ads API integration with automatic OAuth 2.0 authentication Connect Google Ads API directly to MCP Clients with seamless OAuth 2.0 authentication, automatic token refresh, GAQL querying, and keyword research capabilities.
Last updated -
27
Python
MIT License

View all related MCP servers