# 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)